Read Latest Documentation - Browse GitHub Code Repository
The only thing worse than documentation never written, is documentation written but never discovered.
portray is a Python3 command line tool and library that helps you create great documentation websites for your Python projects with as little effort as possible.
Key Features:
portray
. Just run portray
in the root of your Python project and it will find your documentation.portray
websites are easy to host on GitHub pages and other similar services as they are outputted as standard static HTML websites.portray
will automatically include your project's .md
files and render them into HTML. It will also find and render Markdown within __doc__
strings.portray
doesn't have to be configured, you still can fully configure it within the standard pyproject.toml
file.portray
exposes a clean and simple Python API.portray
makes all of your documentation, even autogenerated code references, free-text searchable.portray
is compatible with all existing MkDocs Themes.Under the hood, portray combines the Markdown documentation rendering capabilities provided by MkDocs with the automatic reference documentation generated by pdocs.
The following guides should get you up and running with a documentation website in no time.
pip3 install portray
within your project's virtual environment.portray in_browser
to test and portray on_github_pages
to deploy.[tool.portray]
section of your pyproject.toml
file.I create a lot of Python projects and I've always wanted a quick way to build documentation sites for them that included both manually written guides and autogenerated reference documentation. Tools have improved over the years, but still nothing has given me this experience out of the box. Portray isn't a competitor for the 2 newer Python documentation projects (pdocs and MkDocs), rather it is melding of them together to give me the quick to create and comprehensive documentation website generation I've always wanted.
Thanks and I hope you too find portray
useful!
~Timothy Crosley