Documentation: Improve automatically generated documentation (for https://ncusi.github.io/PatchScope)#127
Merged
Conversation
The mkdocs-typer plugin hasn't been updated in over a year, and there have been a number of changes to Typer since then. One important change is that Typer now has its own documentation generation system via the `typer <module> utils docs` command. The mkdocs-typer2 plugin simply leverages that system to generate the documentation for your Typer CLIs. There were some problems with mkdocs-typer plugin because of the way the 'typer' library is used in this project, and the workaround worked only partially: bruce-szalwinski/mkdocs-typer#18 Note that mkdocs-typer2 is plugin, while mkdocs-typer was markdown extension.
The Numpydoc format (https://numpydoc.readthedocs.io/en/latest/format.html) is much better supported by the mkdocstring-python's Graffle engine than Sphinx format (https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html). See for example the Graffle documentation about different docstring formats: https://mkdocstrings.github.io/griffe/reference/docstrings/ it is detailed for Google-style and Numpydoc, but sparse for Sphinx-style. The API documentation was not well rendered for Sphinx style. It seems like Sphinx style of docstring is beter supported for reST based documentation generators, like ReadTheDocs (rather than MkDocs). The main bulk of converting from Sphinx-style to Numpydoc-style was done with the help of docconvert (https://github.com/cbillingham/docconvert). It did require some manual corrections though, mostly about the types of returned values.
The introduction was borrowed, with some adjustments, from the main README.md. For example, hyperlinks to tools documentation were added. Also added documentation to for `diffinsights-web` command line tool.
Adjust the docstring so that MkDocs generated HTML documentation renders correctly. Without, for example, <placeholder> rendering empty (now uses the `<placeholder>` instead).
Adjust the doctring for the src/diffannotator/annotate.py file, and add doctring for the common() function - which is the documentation of the diff-annotate command as a whole (previously there only individual subcommands had docstring and were documented).
Note that as not a native English speaker, some of those improvements may not be entirely correct (especially added articles). Some of changes in this commit were fixes for the automated docstring style conversion from Sphinx-style (reST) to Numpydoc-style.
Add the doctring for the common() function - which is the documentation of the diff-gather-stats command as a whole (previously there only individual subcommands had docstring, and were documented).
Add the doctring for the main() function, which is the entry function that implements the diffinsights-web command (diffinsights_web.main). This is intended to provide description for this CLI command. Unfortunately, for some reason, event while `typer <module> utils docs` run just fine and produces expected output, mkdocs-typer2 plugin does not render documentation for diffinsights-web. Bug report: syn54x/mkdocs-typer2#15
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
To improve CLI documentation, there was switch from
mkdocs-typermarkdown extension tomkdocs-typer2plugin. Docstring for CLI entry points were improved or added. Also added introduction to CLI.To improve API documentation, the PatchScope project switched from Sphinx to Numpydoc style docstrings, mainly because there is much better support for Numpydocs style in mkdocstrings-python (Python handler for mkdocstrings).