Overview:

Portray is a Python3 command line tool and library that helps developers create great documentation websites for their Python projects with minimal effort. It is a combination of pdocs and MkDocs, offering a quick and comprehensive solution for generating documentation websites. With zero configuration needed, portray automatically finds and includes project's .md files and renders them into HTML. It also supports rendering Markdown within __doc__ strings. The tool is fully configurable and can be easily programmed using a clean Python API. Portray websites are statically generated and can be hosted on platforms like GitHub pages. Overall, Portray aims to provide developers with an efficient and hassle-free way of creating and managing project documentation.

Features:

Zero-Config: No configuration required; simply run portray in the root of your Python project and it will find your documentation.
Statically Generated: Portray websites are easily hostable on platforms like GitHub pages as they are outputted as standard static HTML websites.
Markdown Aware: Automatically includes and renders project's .md files and supports rendering Markdown within __doc__ strings.
Fully Configurable: Can be fully configured within the standard pyproject.toml file, although configuration is optional.
Easily Programmable: Exposes a clean and simple Python API, allowing easy automation and integration.
Searchable: All documentation, including autogenerated code references, is searchable out of the box.
Themeable: Compatible with all existing MkDocs themes.

Summary:

Portray is a Python tool and library that simplifies the process of creating comprehensive documentation websites for Python projects. It combines the capabilities of pdocs and MkDocs to offer a convenient solution for developers. With minimal configuration required, Portray automatically generates static HTML websites from project files and supports rendering Markdown. It is easily programmable and can be integrated with existing workflows. By providing features like searchability and theme compatibility, Portray aims to improve the documentation experience for Python developers.

Timothycrosley

Portray