docs: update documentation (#247)

* chore: add docs-dev makefile target

* docs: update documentation

* fix link

* remove duplicate dev guide content

CONTRIBUTING.rst

@@ -55,41 +55,27 @@ If you are proposing a feature:
 Get Started!
 -------------
 
-Ready to contribute? Here's how to set up `hcloud-python` for local development.
+Ready to contribute? Here's how to set up ``hcloud-python`` for local development.
 
-1. Fork the `hcloud-python` repo on GitHub.
+1. Fork the ``hcloud-python`` repo on GitHub.
 2. Clone your fork locally::
 
     $ git clone [email protected]:your_name_here/hcloud-python.git
 
-3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
-
-    $ mkvirtualenv hcloud-python
-    $ cd hcloud-python/
-    $ python setup.py develop
-
+3. Read the ``Development`` section in the ``README.md``, to setup your development environment.
 4. Create a branch for local development::
 
     $ git checkout -b name-of-your-bugfix-or-feature
 
    Now you can make your changes locally.
 
-5. When you're done making changes, check that your changes pass pre-commit and the
-   tests, including testing other Python versions with tox::
-
-    $ tox -e pre-commit
-    $ python setup.py test or py.test
-    $ tox
-
-   To get pre-commit and tox, just pip install them into your virtualenv.
-
-6. Commit your changes and push your branch to GitHub::
+5. Commit your changes and push your branch to GitHub::
 
     $ git add .
     $ git commit -m "Your detailed description of your changes."
     $ git push origin name-of-your-bugfix-or-feature
 
-7. Submit a pull request through the GitHub website.
+6. Submit a pull request through the GitHub website.
 
 Pull Request Guidelines
 ------------------------
@@ -99,27 +85,6 @@ Before you submit a pull request, check that it meets these guidelines:
 1. The pull request should include tests.
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
-   feature to the list in README.rst.
-3. The pull request should work for Python 2.7, 3.5 and 3.6, and for PyPy. Check
-   https://travis-ci.org/hetznercloud/hcloud-python/pull_requests
-   and make sure that the tests pass for all supported Python versions.
-
-Tips
------
-
-To run a subset of tests::
-
-$ py.test tests.test_hetznercloud
-
-
-How to release
----------------
-
-A reminder for the maintainers on how to release a new version.
-Make sure all your changes are committed (including an entry in CHANGELOG.rst).
-Then run::
-
-1. Change the version under /hcloud/version.py
-2. Push the change to the `master` branch and tag an new release through the `Github UI <https://github.com/hetznercloud/hcloud-python/releases>`_.
-
-Travis will then deploy to PyPI if tests pass.
+   feature to the list in README.md.
+3. The pull request should work for all the versions of Python the library supports, and
+   for PyPy.

Makefile

@@ -20,5 +20,14 @@ docs: venv
 	$(MAKE) -C docs html
 	xdg-open docs/_build/html/index.html
 
+docs-dev: venv docs
+	venv/bin/watchmedo shell-command \
+		--patterns="*.py;*.rst;*.md" \
+		--ignore-pattern=".git/*" \
+		--recursive \
+		--drop \
+		--command="$(MAKE) -C docs html" \
+		.
+
 clean:
 	git clean -xdf

README.md

@@ -0,0 +1,92 @@
+# Hetzner Cloud Python
+
+[![](https://github.com/hetznercloud/hcloud-python/actions/workflows/test.yml/badge.svg)](https://github.com/hetznercloud/hcloud-python/actions/workflows/test.yml)
+[![](https://github.com/hetznercloud/hcloud-python/actions/workflows/lint.yml/badge.svg)](https://github.com/hetznercloud/hcloud-python/actions/workflows/lint.yml)
+[![](https://readthedocs.org/projects/hcloud-python/badge/?version=latest)](https://hcloud-python.readthedocs.io)
+[![](https://img.shields.io/pypi/pyversions/hcloud.svg)](https://pypi.org/project/hcloud/)
+
+Official Hetzner Cloud python library.
+
+The library's documentation is available at [hcloud-python.readthedocs.io](https://hcloud-python.readthedocs.io), the public API documentation is available at [docs.hetzner.cloud](https://docs.hetzner.cloud).
+
+## Usage
+
+Install the `hcloud` library:
+
+```sh
+pip install hcloud
+```
+
+For more installation details, please see the [installation docs](https://hcloud-python.readthedocs.io/en/stable/installation.html).
+
+Here is an example that creates a server and list them:
+
+```python
+from hcloud import Client
+from hcloud.images.domain import Image
+from hcloud.server_types.domain import ServerType
+
+client = Client(token="{YOUR_API_TOKEN}")  # Please paste your API token here
+
+# Create a server named my-server
+response = client.servers.create(
+    name="my-server",
+    server_type=ServerType(name="cx11"),
+    image=Image(name="ubuntu-22.04"),
+)
+server = response.server
+print(f"{server.id=} {server.name=} {server.status=}")
+print(f"root password: {response.root_password}")
+
+# List your servers
+servers = client.servers.get_all()
+for server in servers:
+    print(f"{server.id=} {server.name=} {server.status=}")
+```
+
+For more details, please see the [API reference](https://hcloud-python.readthedocs.io/en/stable/api.html).
+
+You can find some more examples under the [`examples/`](https://github.com/hetznercloud/hcloud-python/tree/main/examples) directory.
+
+## Supported Python versions
+
+We support python versions until [`end-of-life`](https://devguide.python.org/versions/#status-of-python-versions).
+
+## Development
+
+First, create a virtual environment and activate it:
+
+```sh
+make venv
+source venv/bin/activate
+```
+
+You may setup [`pre-commit`](https://pre-commit.com/) to run before you commit changes, this removes the need to run it manually afterwards:
+
+```sh
+pre-commit install
+```
+
+You can then run different tasks defined in the `Makefile`, below are the most important ones:
+
+Build the documentation and open it in your browser:
+
+```sh
+make docs
+```
+
+Run tests using the current `python3` version:
+
+```sh
+make test
+```
+
+You may also run the tests for multiple `python3` versions using `tox`:
+
+```sh
+tox .
+```
+
+## License
+
+The MIT License (MIT). Please see [`License File`](https://github.com/hetznercloud/hcloud-python/blob/main/LICENSE) for more information.

docs/api.rst

@@ -1,4 +1,4 @@
-hcloud-python API
+API References
 ==================
 
 Main Interface

docs/index.md

@@ -0,0 +1,15 @@
+:::{toctree}
+:maxdepth: 4
+:hidden:
+
+self
+installation.rst
+api.rst
+Hetzner Cloud API Documentation <https://docs.hetzner.cloud>
+contributing.rst
+changelog.md
+
+:::
+
+:::{include} ../README.md
+:::

docs/installation.rst

@@ -38,26 +38,22 @@ Hetzner Cloud Python is also available as a ``conda``-package via `conda-forge`.
 From sources
 ------------
 
-The sources for Hetzner Cloud Python can be downloaded from the `Github repo`_.
+The sources for Hetzner Cloud Python can be downloaded from the Github repo.
 
 You can either clone the public repository:
 
 .. code-block:: console
 
     $ git clone git://github.com/hetznercloud/hcloud-python
 
-Or download the `tarball`_:
+Or download the tarball:
 
 .. code-block:: console
 
-    $ curl  -OL https://github.com/hetznercloud/hcloud-python/tarball/master
+    $ curl  -OL https://github.com/hetznercloud/hcloud-python/tarball/main
 
 Once you have a copy of the source, you can install it with:
 
 .. code-block:: console
 
-    $ python setup.py install
-
-
-.. _Github repo: https://github.com/hetznercloud/hcloud-python
-.. _tarball: https://github.com/hetznercloud/hcloud-python/tarball/master
+    $ pip install .