docs: update README and documentation guide

README.md

@@ -35,9 +35,18 @@ pip install emnify-sdk
 
 Read more about working with the Python SDK and the underlying concepts in the [emnify product documentation](https://docs.emnify.com/sdks/python).
 
+### API reference
+
+We use [sphinx-autoapi](https://github.com/readthedocs/sphinx-autoapi) to auto-generate the API reference documentation within this repository. 
+This documentation is hosted separately on [GitHub Pages](https://emnify.github.io/emnify-sdk-python/autoapi/index.html). 
+
+> 🗺️ _Note: We plan to eventually migrate the API reference documentation into our [product documentation platform](https://docs.emnify.com/)._
+
+See our [documentation guide](./docs/README.md) if you're interested in contributing to the API reference or running the documentation locally.
+
 ## Contributing
 
-If you've found a bug or would like to add new features, [open an issue](https://github.com/emnify/emnify-sdk-python/issues/new) or [create a pull request](https://github.com/emnify/emnify-sdk-python/pulls) to this Github repository.
+If you've found a bug or want to add new features, [open an issue](https://github.com/emnify/emnify-sdk-python/issues/new) or [create a pull request](https://github.com/emnify/emnify-sdk-python/pulls) to this GitHub repository.
 
 See our [development guide](./DEVELOPMENT.md) for how to get started.
 

docs/README.md

@@ -1,9 +1,36 @@
-### Generate Documentation Locally
+# Documentation guide
 
-1) Build a container
+## Prerequisites
 
-`docker build . -f docs/Dockerfile.dev -t emnify/python-sdk-docs`
+- [Docker](https://www.docker.com/)
 
-2) Run docgen
-   1) mac/linux `docker run -t -v $(pwd):/docs emnify/python-sdk-docs`
-   2) for windows `docker run -t -v %cd%:/docs emnify/python-sdk-docs`
+## Running the documentation locally
+
+If you haven't already, clone and move into this repository:
+
+```shell
+git clone https://github.com/emnify/emnify-sdk-python.git
+cd emnify-sdk-python
+```
+
+From the root, build the Docker container:
+
+```shell
+docker build . -f docs/Dockerfile.dev -t emnify/python-sdk-docs
+```
+
+2. Run docgen
+
+```shell
+# macOS and Linux
+docker run -t -v $(pwd):/docs emnify/python-sdk-docs
+```
+
+```shell
+# Windows
+docker run -t -v %cd%:/docs emnify/python-sdk-docs
+```
+
+This command sets up (or updates) the `build_sphinx` project to run from inside the `docs/` directory. 
+
+Once complete, you can preview the documentation as HTML pages in `docs/build_sphinx`.