Configuring portray

Hopefully, portray's automatic configuration will pick up everything you need to document your project. If not, portray enables configuration for every aspect of your documentation website using Python's standard pyproject.toml file. Configuration options should be placed within a tool.poetry section of your config file:

[tool.portray]
output_dir = "documentation_website"

portray itself comes with a handful of configuration options:

  • docs_dir: The directory (beyond your project root directory) where your markdown documentation is located. Defaults to "docs".
  • extra_dirs: A list of additional directories to make available during static documentation building. Defaults to ["art", "images", "media"].
  • extra_markdown_extensions: A list of additional markdown extensions to use when rendering documentation as HTML.
  • output_dir: The directory to output your generated documentation website when using portray as_html. Defaults to "site".
  • port: The port to use when serving your website locally. Defaults to 8000.
  • host: The host to use when serving your website locally. Defaults to 127.0.0.1.
  • labels: Label remappings for documentation pages.
  • modules: A List of Python modules to generate reference documentation for.
  • append_directory_to_python_path: If set to true (the default) appends the projects root directory to the PYTHON_PATH before producing documentation.
  • include_reference_documentation: If set to true (the default) automatic reference documentation is produced by pdocs to live alongside your manually written documentation.

Beyond portray's direct configuration options, you can modify any of MkDocs or pdocs configuration options in the same pyproject.toml file. Simply nest their configuration under a .mkdocs or .pdoc3.

For example, to change the MkDocs theme configuration used for portray the following is set in pyproject.toml:

[tool.portray.mkdocs.theme]
favicon = "art/logo_small.png"
logo = "art/logo_small.png"
name = "material"
palette = {primary = "blue grey", accent = "pink"}

TOML doesn't behave 1:1 with YAML, and as a result, in some cases portray forces a stricter form of configuration options. For instance, to set up a custom navigation structure with portray, you can either specify just a flat list of file names, or a list of mappings of {LABEL: FILENAME or LIST_OF_MAPPING} but not a mix of both. This still allows as much customization as is permitted by mkdocs just with more consistency enforced. The recommended form is always to use lists of mappings. Here is what that would look like for portray's documentation site if it chose to specify the navigation manually:

[[tool.portray.mkdocs.nav]]
Home = "README.md"

[[tool.portray.mkdocs.nav]]
Changelog = "CHANGELOG.md"

[[tool.portray.mkdocs.nav]]
Troubleshooting = "TROUBLESHOOTING.md"

[[tool.portray.mkdocs.nav]]
    [[tool.portray.mkdocs.nav.Contributing]]
    "1. Contributing Guide" = "docs/contributing/1.-contributing-guide.md"

    [[tool.portray.mkdocs.nav.Contributing]]
    "2. Coding Standard" = "docs/contributing/2.-coding-standard.md"

    [[tool.portray.mkdocs.nav.Contributing]]
    "3. Code of Conduct" = "docs/contributing/3.-code-of-conduct.md"

    [[tool.portray.mkdocs.nav.Contributing]]
    "4. Acknowledgements" = "docs/contributing/4.-acknowledgements.md"

[[tool.portray.mkdocs.nav]]
    [[tool.portray.mkdocs.nav."Quick Start"]]
    "1. Installation" = "docs/quick_start/1.-installation.md"

    [[tool.portray.mkdocs.nav."Quick Start"]]
    "2. CLI" = "docs/quick_start/2.-cli.md"

    [[tool.portray.mkdocs.nav."Quick Start"]]
    "3. API" = "docs/quick_start/3.-api.md"

    [[tool.portray.mkdocs.nav."Quick Start"]]
    "4. Configuration" = "docs/quick_start/4.-configuration.md"

Note that the above utilizes TOMLs double bracket syntax to specify a List of Dicts.

For more information about available configuration options see MkDocs configuration and pdoc3 configuration.

Warning

While portray allows configuring any aspect of MkDocs or pdoc3, it only allows that configuration to be defined in a pyproject.toml file. Any other configuration files normally used for these projects will be ignored.