Add published API documentation #24
Conversation
vinceatbluelabs
changed the title
| """Get connection info for specified database.""" | ||
| """Get connection info for specified database. | ||
|
|
||
| :param db_name: Alias for the particular database endpoint and account to connect to. ['a','b','c'] corresponds to 'a-b-c' on the db-facts command-line. |
There was a problem hiding this comment.
[flake8] E501 line too long (157 > 100 characters)
There was a problem hiding this comment.
I punted on this one; I couldn't figure out how to add a continuation to a directive in RST. Maybe it's worth flipping over to google format docstrings? Not sure if this is solvable there or not, just can't remember if you had a take on that. I think the hypermodern series uses google format instead of RST.
The default sphinx API doc generation doesn't seem to set TYPE_CHECKING, which results in dropping our use of TypedDict, Literal and other things we don't use by default to avoid extra dependencies.
| configured database named 'redshift'. Other parts of this chain can | ||
| be found in the [ws-scripts](https://github.com/bluelabsio/ws-scripts) | ||
| repo. | ||
|
|
There was a problem hiding this comment.
Whoops! We still had a reference to an internal repo. Getting this stuff packaged up and open sourced is in the backlog, but not on the critical path to get 1.0 of records-mover out.
| 'db', | ||
| 'DBFacts', | ||
| 'UserErrorException' | ||
| ] |
There was a problem hiding this comment.
Using __all__ helps clarify the public API and also gives Sphinx the hint to put the documentation for these in the overall package. These are pretty fundamental, so I'm more comfortable having them in the top-level package than I am with the names of the subpackages they currently live in :)
| .. automodule:: db_facts | ||
| :members: | ||
| :undoc-members: | ||
| :show-inheritance: |
There was a problem hiding this comment.
This is hand-tuned to show the bits we want to document - the public API as well as the details about the provided jinja contexts. Having the rest marked private with a leading underscore may allow us to have this file be auto-generated so we won't have to tweak it if more public API is added in the future--I may play around with that and see what the amount of effort is there.
| # Catch-all target: route all unknown targets to Sphinx using the new | ||
| # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
| %: Makefile | ||
| @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
There was a problem hiding this comment.
This file is stock from the auto-generated template so far.
| # The default sphinx doesn't seem to set TYPE_CHECKING, which | ||
| # results in dropping our use of TypedDict, Literal and other | ||
| # things we don't use by default to avoid extra dependencies. | ||
| 'sphinx_autodoc_typehints', |
There was a problem hiding this comment.
The net result from sphinx_autodoc_typehints could be better - but it's definitely better than seeing the detailed return value from db() as just dict.
| # Ensure TYPE_CHECKING is set to True so we document using types from | ||
| # typing_extensions (e.g., TypedDict) | ||
| # | ||
| set_type_checking_flag = True |
There was a problem hiding this comment.
I added this section and flag.
vinceatbluelabs
changed the title
Docs published here! https://db-facts.readthedocs.io/en/published_docs/
This adds public API documentation only; the existing markdown visible in GitHub is not part of things yet. I'm inclined to wait until after records-mover 1.0 to worry about that.