pytkdocs_tweaks

Some custom tweaks for pytkdocs.

For use as part of the documentation-generation-for-Python stack that comprises mkdocs, mkdocs-material, mkdocstrings and pytkdocs.

• Types are ubiquitously displayed in the way you import them: package.Foo (rather than being a mix of where they're defined: package.subpackage.foomodule.Foo or just their name: Foo).
• Only public base classes are shown (rather than every base class).
• Adds short documentation for inherited and implemented methods, e.g. "Inherited from package.Foo." (Rather than nothing at all.)
  • An inherited method is one inherited from a base class. An implemented method is one overriding an abstract method on a base class.
• Sets a custom 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).
• Adds an abstractmethod/abstractproperty property to appear in the documentation instead. (Useful when specifying abstract base classes.)
• Removed the dataclass and special properties that appear in the documentation. (I find that these just add visual noise.)
• Removed the -> None return annotation on __init__ methods.
• Function-valued defaults now display as just <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.)

Installation

pip install pytkdocs_tweaks

Requires Python 3.8+ and pytkdocs==0.15.0.

Usage

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`.