Skip to content

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

Merged
merged 20 commits into from
Nov 26, 2024
Merged

Adding docstrings and introducing sphinx draft #12

merged 20 commits into from
Nov 26, 2024

Conversation

giograno
Copy link
Member

@giograno giograno commented Nov 22, 2024

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

  • Adding docstrings. They are needed for the sphinx.ext.autodoc plugin (to generate the API reference);
  • Introducing a minimal structure for the website generated by sphinx. It includes a brief installation guide, a link to our Python SDK page in our docs, and autogenerated API references.
  • Adding a workflow that: i) generates the website; ii) pushes the built HTML files on a gh-pages branch. From this branch, we can easily create a static website on GH pages.

@giograno giograno requested a review from alexrashed November 22, 2024 15:30
@giograno giograno requested a review from HarshCasper November 25, 2024 18:53
@giograno giograno marked this pull request as ready for review November 25, 2024 18:53
Copy link
Member

@alexrashed alexrashed left a 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)
Copy link
Member

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?

@giograno giograno merged commit 41e6ca5 into main Nov 26, 2024
1 check passed
@giograno giograno deleted the docs branch November 26, 2024 17:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants