Skip to content

Command Line Usage

Once installed, 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.

Running 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).

Running 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 --port and --host argument.


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 pyproject.toml file:

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 pyproject.toml.

Outputting Documentation Locally

You can also output portray's generated documentation to a local directory. To do so run portray as_html:

By default the generated documentation is outputted into a site subdirectory. 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 -o DIRECTORY.

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 using 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 pyproject.toml file.