Your Project with Great Documentation
Project description
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:
- Zero-Config: No configuration is necessary to use
portray. Just runportrayin the root of your Python project and it will find your documentation. - Statically Generated:
portraywebsites are easy to host on GitHub pages and other similar services as they are outputted as standard static HTML websites. - Markdown Aware:
portraywill automatically include your project's.mdfiles and render them into HTML. It will also find and render Markdown within__doc__strings. - Fully Configurable: While
portraydoesn't have to be configured, you still can fully configure it within the standardpyproject.tomlfile. - Easily Programmable:
portrayexposes a clean and simple Python API. - Searchable: Out of the box,
portraymakes all of your documentation, even autogenerated code references, free-text searchable. - Themeable:
portrayis 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.
Quick Start
The following guides should get you up and running with a documentation website in no time.
- Installation - TL;DR: Run
pip3 install portraywithin your project's virtual environment. - Command Line Usage - TL;DR: Run
portray in_browserto test andportray on_github_pagesto 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.tomlfile.
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file portray-1.8.0.tar.gz.
File metadata
- Download URL: portray-1.8.0.tar.gz
- Upload date:
- Size: 13.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.2.2 CPython/3.10.6 Linux/6.0.6-76060006-generic
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | a9dd2973a0235051c5b68a29390c3eeee192dc248cc2d944452ee9c02423b47d |
|
| MD5 | 3ecd7a4aefb28c3d4a9f7c10796ffc1a |
|
| BLAKE2b-256 | 31c5647feff9c1a65c403594e51e8ebc9eb93b71e77808c159cf688970585715 |
File details
Details for the file portray-1.8.0-py3-none-any.whl.
File metadata
- Download URL: portray-1.8.0-py3-none-any.whl
- Upload date:
- Size: 14.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.2.2 CPython/3.10.6 Linux/6.0.6-76060006-generic
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | c7ee981b51f9b41b60b04c1351e1b61edd291049d10c45f7c8f05897caa6a931 |
|
| MD5 | 11512d49d135c114555fdc1f7d750f13 |
|
| BLAKE2b-256 | 319973ee12584f7186b99ce07f130a1f8b727e72008f4f767552c227ff1a5fb7 |
