Home

Awesome

portray - Your Project with Great Documentation.


PyPI version Test Status Lint Status codecov Join the chat at https://gitter.im/timothycrosley/portray License Downloads


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.

Example Usage Gif

Key Features:

Under the hood, portray combines the Markdown documentation rendering capabilities provided by MkDocs with the automatic reference documentation generated by pdocs.

Quick Start

The following guides should get you up and running with a documentation website in no time.

  1. Installation - TL;DR: Run pip3 install portray within your project's virtual environment.
  2. Command Line Usage - TL;DR: Run portray in_browser to test and portray on_github_pages to deploy.
  3. API Usage - TL;DR: Everything available via the CLI is also easily available programmatically from within Python.
  4. Configuration - TL;DR: Put all configuration within a [tool.portray] section of your pyproject.toml file.

Why Create Portray?

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