Skip to content
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

Add reference documentation generated from docstrings #311

Closed
simonw opened this issue Aug 10, 2021 · 4 comments
Closed

Add reference documentation generated from docstrings #311

simonw opened this issue Aug 10, 2021 · 4 comments

Comments

@simonw
Copy link
Owner

simonw commented Aug 10, 2021

Using https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

I'm not a big fan of this kind of documentation because it so often comes in place of narrative documentation - but the library has great narrative documentation now, so the reference documentation can link to it in places.

This will also encourage me to add good docstrings everywhere, useful for IDEs and suchlike.

@simonw
Copy link
Owner Author

simonw commented Aug 10, 2021

make livehtml wasn't picking up changes I made to the docstrings .py files.

Fix was to change it to this:

sphinx-autobuild -a -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0) --watch ../sqlite_utils

See https://github.com/executablebooks/sphinx-autobuild#relevant-sphinx-bugs - though that suggested -a but didn't suggest --watch, which is a tip I got from https://github.com/executablebooks/sphinx-autobuild#working-on-a-sphinx-html-theme

@simonw
Copy link
Owner Author

simonw commented Aug 10, 2021

I'm going to use this as an excuse to add a bunch more type signatures too, refs #266.

@simonw
Copy link
Owner Author

simonw commented Aug 10, 2021

Work will continue in PR #312.

@simonw
Copy link
Owner Author

simonw commented Aug 10, 2021

simonw added a commit that referenced this issue Aug 10, 2021
simonw added a commit that referenced this issue Aug 10, 2021
@simonw simonw closed this as completed Aug 11, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant