portray
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:
- Zero-Config: No configuration is necessary to use
portray
. Just runportray
in the root of your Python project and it will find your documentation. - Statically Generated:
portray
websites are easy to host on GitHub pages and other similar services as they are outputted as standard static HTML websites. - Markdown Aware:
portray
will automatically include your projects.md
files and render them into HTML. It will also find and render Markdown within__doc__
strings. - Fully Configurable: While
portray
doesn't have to be configured, you still can fully configure it within the standardpyproject.toml
file. - Easily Programmable:
portray
exposes a clean and simple Python API. - Searchable: Out of the box
portray
makes all of your documentation, even autogenerated code references, free-text searchable. - Themeable:
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 pdoc3.
Quick Start
The following guides should get you up and running with a documentation website in no time.
- Installation - TL;DR: Run
pip3 install portray
within your projects virtual environment. - Command Line Usage - TL;DR: Run
portray in_browser
to test andportray on_github_pages
to deploy. - API Usage - TL;DR: Everything available via the CLI is also easily available programmatically from within Python.
- Configuration - TL;DR: Put all configuration within a
[tool.portray]
section of yourpyproject.toml
file.