Make documentation relevant #237
Merged
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
DifferentialOrange
changed the base branch from
master
to
DifferentialOrange/gh-212-cleanup-python-2
DifferentialOrange
force-pushed
the
DifferentialOrange/gh-67-relevant-docs
branch
from
17c8dfd to
6826b50
Compare
Merged
DifferentialOrange
force-pushed
the
DifferentialOrange/gh-67-relevant-docs
branch
from
6826b50 to
46bcca2
Compare
Base automatically changed from
DifferentialOrange/gh-212-cleanup-python-2
to
master
October 10, 2022 11:18
DifferentialOrange
force-pushed
the
DifferentialOrange/gh-67-relevant-docs
branch
from
46bcca2 to
7d2fa80
Compare
DifferentialOrange
force-pushed
the
DifferentialOrange/gh-67-relevant-docs
branch
4 times, most recently
from
29c549a to
6619781
Compare
Merged
Default 'classic' theme [1] was used by Python 2 documentation. It's not well-suited for modern resolutions and it's sidebar width isn't configurable, which is crucial for modules API ToC correct display. 1. https://www.sphinx-doc.org/en/master/usage/theming.html Part of #67
Even though index, guide and quick start documentation pages have Russian translation. it isn't published on readthedocs [1]. Since we don't plan to have a Russian connector documentation for now, this patch removes the files. 1. https://tarantool-python.readthedocs.io/en/latest/ Part of #67
Add or update docstings for submodule files contents. Submodules are not meant to be used directly in code, but their descriptions will be imported automatically to core module API description. It also may help developers of this module. Every submodule that could be of use is indexed in documentation now. Set sphinx autodoc module to describe members and inherited members by default. Dataclass with factories display is not parsed correctly, see [1] issue. 1. sphinx-doc/sphinx#10893 Part of #67
Update core module docstring and autodoc parameters. Part of #67
Due to DBAPI requirements, Connection and MeshConnection classes expose exceptions as attributes. tarantool module also exposes several exceptions. sphinx raises warnings about duplicate object description due to multiple exception references. Since there is no way to put ``:noindex:`` in docstrings [1] and other solutions (like ``:meta private:``) are completely remove attribute descriptions, this patch removes indexes with rst-level workarounds. 1. https://stackoverflow.com/questions/66736786/can-i-use-noindex-in-python-docstring-with-sphinx-autodoc Part of #67
Sidebar with links was removed since it overlaps other elements. Some descriptions were reduced since all required info is now provided in API documentation. Part of #67
Part of #67
Make README consistent with documentation index page. Remove Tarantool 1.6 guides since the version was deprecated several years ago. Part of #67
DifferentialOrange
force-pushed
the
DifferentialOrange/gh-67-relevant-docs
branch
from
6619781 to
589d3ff
Compare
|
Add CHANGELOG entries where it seemed relevant. |
oleg-jukovec
approved these changes
Oct 11, 2022
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.
This PR updates existing tarantool-python module documentation and adds descriptions where they were missing. See commit messages for more detailed info.
To build documentation, first you must install its build requirements:
Then run
You may host local documentation server with
Open
localhost:8000in your browser to read the docs.Closes #67
This PR does not yet provide publishing documentation with CI, see #238. readthedocs module documentation will remain outdated until this PR would be reviewed thoroughly.