Generate documentation of private members through sphinx docs #2831
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Pull Request Test Coverage Report for Build 5964715633
💛 - Coveralls |
|
what's with the Tests / docs step failing here? |
I expect sphinx wasn't parsing the private methods at all before so didn't detect formatting problems. I'll take a look. |
CyberDem0n
reviewed
Sep 7, 2023
| @@ -257,7 +257,7 @@ def __init__(self, configfile: str, | |||
|
|
|||
| * file or directory path passed as command-line argument (*configfile*), if it exists and the file or | |||
| files found in the directory can be parsed (see :meth:`~Config._load_config_path`), otherwise | |||
| * YAML file passed via the environment variable (see :cvar:`PATRONI_CONFIG_VARIABLE`), if the referenced | |||
| * YAML file passed via the environment variable (see :attr:`PATRONI_CONFIG_VARIABLE`), if the referenced | |||
There was a problem hiding this comment.
Hmm, in the class docstring it is declared as :cvar:. Shouldn't it be here the same?
There was a problem hiding this comment.
Apparently, it's not a valid "domain" according to sphinx command output. Docs are here for what can be used
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects
patroni/postgresql/validator.py
Outdated
Comment on lines
283
to
288
| Load validators from YAML files that were found. | ||
|
|
||
| Recursively walk through ``available_parameters`` directory and load validators of each found YAML file into | ||
| ``parameters`` and/or ``recovery_parameters`` variables. | ||
|
|
||
| Walk through directories in top-down fashion and for each of them: | ||
| * Sort files by name; | ||
| * Load validators from YAML files that were found. |
There was a problem hiding this comment.
Hmmn yes that is odd. Let me revert it and see if there were errors.
There was a problem hiding this comment.
Yep, unrelated. Reverted.
With this commit we make sphinx build API docs for the following things, which were missing up to this point: * `__init__` method of classes; * "private" members (properties, functions, methods, attributes, etc., which name starts with an underscore); * members that are missing a docstring, so we can still reference them with links in the documentation. The third point can be removed later, if we wish, when we reach a point where everything has proper docstrings in the Patroni code base. References: PAT-195. Signed-off-by: Israel Barth Rubio <[email protected]>
…hinx * `:cvar:` is not a valid domain role. Replaced with `:attr:`. * documentation for `consul.base.Consul.__init__` has a single backtick quoted string which is interpreted as a reference which cannot be found. Therefore, the docstring has been copied as a block quote. * various list spacing problems and indentation problems. * code blocks added where indentation is interpreted incorrectly * literal string quoting issues.
matthbakeredb
force-pushed
the
feature/sphinx-doc-private-members
branch
from
78a4b15
to
1e38a7a
Compare
|
👍 |
1 similar comment
|
👍 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
With this commit we make sphinx build API docs for the following things, which were missing up to this point:
__init__method of classes;The third point can be removed later, if we wish, when we reach a point where everything has proper docstrings in the Patroni code base.
References: PAT-195.