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.
Tip
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:
[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 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.