Some custom tweaks to the results produced by pytkdocs.
APACHE-2.0 License
Some custom tweaks for pytkdocs.
For use as part of the documentation-generation-for-Python stack that comprises mkdocs, mkdocs-material, mkdocstrings and pytkdocs.
package.Foo
(rather than being a mix of where they're defined: package.subpackage.foomodule.Foo
or just their name: Foo
).package.Foo
." (Rather than nothing at all.)
typing.GENERATING_DOCUMENTATION = True
flag that you can use to detect when documentation generation is happening and customise things if desired (documentation generation imports the library you're documenting).abstractmethod
/abstractproperty
property to appear in the documentation instead. (Useful when specifying abstract base classes.)dataclass
and special
properties that appear in the documentation. (I find that these just add visual noise.)-> None
return annotation on __init__
methods.<function foo>
rather than <function foo at 0x7f5428d27a60>
.Note that you must run the mkdocs
command twice, as these custom tweaks write a cache to disk -- listing all the public objects -- that are then used on the second run. If you see a .all_objects.cache
file appear -- this is why. (You may wish to add the file to your .gitignore
.)
pip install pytkdocs_tweaks
Requires Python 3.8+ and pytkdocs==0.15.0
.
In your mkdocs.yml
:
plugins:
- search # default plugin, need to re-enable when using manual plugins
- mkdocstrings:
handlers:
python:
setup_commands:
- import pytkdocs_tweaks
- pytkdocs_tweaks.main()
selection:
inherited_members: true # allow looking up inherited members
rendering:
show_root_heading: true #
show_root_full_path: true # have e.g. `package.Foo` display correctly, rather than e.g. just `Foo`.