-
Notifications
You must be signed in to change notification settings - Fork 0
Adding docstrings and introducing sphinx draft #12
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Awesome! Nice push towards industry-standard auto-generated SDK docs! 🚀
I only added a few comments, mostly general questions on the initial setup and the usage of Sphinx. Nothing blocking a merge / an initial deployment from my side though! 💯
I think it's necessary to get the docs as close to the actual code to make sure that it really stays in sync! 💯 Considering the state of the SDK and the potential to grow in docs, I think it would be absolutely reasonable (at least in the first place) to have its own docs pages published via GH pages and linked from docs.localstack.cloud. 👍🏽
Would be great to get the input from @HarshCasper on this topic: How whould the auto-generated API documentation for the SDK be linked with the docs / how should the two relate to each other from the perspective of developer relations?
@@ -23,6 +23,11 @@ clean-generated: ## Cleanup generated code | |||
generate: ## Generate the code from the OpenAPI specs | |||
./bin/generate.sh | |||
|
|||
sphinx-docs: ## Generate the documentation | |||
($(VENV_RUN); sphinx-apidoc --implicit-namespaces -o docs localstack-sdk-python/localstack) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
question: Should this maybe also just use the sphinx "catch all make target" in line 20 of the Makefile in the docs folder?
We released our first few releases on the Python SDK, but we lack proper documentation.
This PR introduces a documentation site built with sphinx.
Changes
sphinx.ext.autodoc
plugin (to generate the API reference);gh-pages
branch. From this branch, we can easily create a static website on GH pages.