Command Line Usage
portray exposes a simple command line utility for generating documentation websites.
To verify the tool is installed correctly, run
portray from the command line and you should be given the available commands and the version of portray installed.
To get help for any individual subcommand run
portray SUBCOMMAND --help:
Serving Documentation Locally
Before you push documentation out publicly, it's a good idea to test it locally and ensure it looks as desired.
portray server will generate a new static website for your project in a temporary directory and start a local server to allow you to browse it (at localhost:8000 by default).
portray in_browser will do the same as
portray server but also open up the generated website in your environments default web browser for you.
Both commands take an optional
portray does its best to auto determine package modules in order to generate documentation. It does this by looking at
pyproject.toml and your directory name.
If it can't auto determine the Python modules used by your project, you can set them manually in your
[tool.portray] modules = ["portray"]
Or, if you want to avoid configuration files entirely, you can set modules explicitly on the command line using -m (Example:
portray server -m portray.)
Finally, portray pulls .md files from the root of your project and one dedicated documentation directory (defaulting to
docs) by default.
You can change the directory where docs are located by setting the
tool.portray.docs_dir setting in
Outputting Documentation Locally
You can also output
portray's generated documentation to a local directory.
To do so run
By default the generated documentation is outputted into a
If this directory exists for any reason, including previous documentation generation,
the command will fail. Passing in
--overwrite will delete any existing directory
before output to ensure the command passes. You can change the output directory using
Pushing Documentation to GitHub Pages
If you are using GitHub Pages to share your generated documentation you can use
portray on_github_pages to automate the process:
Verifying Project Configuration
You can verify the configuration auto determined by
portray project_configuration in the root of your project:
If anything seems incorrect, or you would want to modify any values, you can override any config option by setting it in the
[tool.portray] section of your