Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
giograno merged 20 commits intomainfromdocs
Nov 26, 2024
Merged

Adding docstrings and introducing sphinx draft#12

giograno merged 20 commits intomainfromdocs
Nov 26, 2024

Conversation

@giograno
Copy link
Member

@giogranogiograno commentedNov 22, 2024•
edited
Loading

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 thesphinx.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 SDKpage in our docs, and autogenerated API references.
  • Adding a workflow that: i) generates the website; ii) pushes the built HTML files on agh-pages branch. From this branch, we can easily create a static website on GH pages.

@giogranogiograno marked this pull request as ready for reviewNovember 25, 2024 18:53
Copy link
Member

@alexrashedalexrashed 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?

./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?

@giogranogiograno merged commit41e6ca5 intomainNov 26, 2024
1 check passed
@giogranogiograno deleted the docs branchNovember 26, 2024 17:59
Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment

Reviewers

@alexrashedalexrashedalexrashed approved these changes

@HarshCasperHarshCasperAwaiting requested review from HarshCasper

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@giograno@alexrashed
[8]ページ先頭
©2009-2025 Movatter.jp