Some custom tweaks to the results produced by pytkdocs (part of mkdocstrings).
Project description
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
andspecial
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`.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
pytkdocs_tweaks-0.0.8.tar.gz
(10.2 kB
view hashes)
Built Distribution
Close
Hashes for pytkdocs_tweaks-0.0.8-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | facc4b8accc93670dec70cdf42d5a576e47f78b40fd168466e608cf84689dca5 |
|
MD5 | d83b76a77d42fe2d762d91f0cab943c9 |
|
BLAKE2b-256 | 8bc4916cce0b1e99d7602d95419a97561115f6ac0c4dc401366002fdc517290a |