mypythontools_cicd.docs package

Helpers with git and github functionality.

mypythontools_cicd.docs.docs_regenerate(docs_path: None | PathLike = None, build_locally: bool = True, git_add: bool = True, keep: Sequence[PathLike] = (), ignore: Sequence[PathLike] = ('modules.rst', '**/*internal.py'), verbosity: Literal[0, 1, 2] = 1) → None[source]

Generate all rst files necessary for sphinx documentation generation with sphinx-apidoc.

It automatically delete rst files from removed or renamed files.

Note

All the files except [‘conf.py’, ‘index.rst’, ‘_static’, ‘_templates’, ‘content/**’], and files in ‘keep’ parameter will be deleted!!! Because if some files would be deleted or renamed, rst would stay and html was generated. If you have some extra files or folders in docs source, add it to content folder or to ‘keep’ parameter.

Function suppose sphinx build and source in separate folders…

Parameters

  • docs_path (None | PathLike, optional) – Where source folder is. If None, will be inferred. Defaults to None.

  • build_locally (bool, optional) – If true, build folder with html files locally. Defaults to True.

  • git_add (bool, optional) – Whether to add generated files to stage. False mostly for testing reasons. Defaults to True.

  • keep (Sequence[PathLike], optional) – List of files and folder names that will not be deleted. Deletion is because if some file would be renamed or deleted, rst docs would still stay. Glob-style patterns can be used, but it’s not recursive, but only first level of source folder is used. Defaults to None.

  • ignore (Sequence[PathLike], optional) – Whether ignore some files from generated rst files. For example It can be python modules that will be ignored or it can be rst files created, that will be deleted. to have no errors in sphinx build for unused modules, or for internal modules. Glob-style patterns can be used. Defaults to (“modules.rst”, “**/*_.py”)

  • verbosity (Literal[0, 1, 2], optional) – If 0, prints nothing, if 1, then one line description of what happened is printed. If 3, all the results from terminal are printed. Defaults to 1.

Note

Function suppose structure of docs like:

-- docs
-- -- source
-- -- -- conf.py
-- -- make.bat
mypythontools_cicd.docs.generate_readme_from_init(git_add: bool = True) → None[source]

Generate README file from __init__.py docstrings.

Because i had very similar things in main __init__.py and in readme. It was to maintain news in code. For better simplicity i prefer write docs once and then generate. One code, two use cases.

Why __init__? - Because in IDE on mouseover developers can see help. Why README.md? - Good for github.com

Parameters

git_add (bool, optional) – Whether to add generated files to stage. False mostly for testing reasons. Defaults to True.