wj-mkdocs

A WaterJuice project.

A PyPI package that bundles a standard MkDocs theme and a small Python program that sets up environment variables to point to the various documents and then executes MkDocs.

This allows config files to use !ENV to point to the actual files wherever they are installed on the system.

Installation

pip install wj-mkdocs

Quick Start

1. Create a mkdocs.yml file with a theme:

   INHERIT: !ENV THEME_STD
   site_name: My Documentation
   
   nav:
     - Home: index.md
   

2. Build the documentation:

   wj-mkdocs -f mkdocs.yml -d docs -o html
   

Themes

To use the theme add the line to the top of the mkdocs.yml file:

INHERIT: !ENV <Theme>

where <Theme> is one of the following:

• THEME_STD - Standard Material for MkDocs theme.

Included Packages

This package includes the following packages so they don't need to be specified:

• mkdocs (1.x.x)
• mkdocs-material (<=9.7.1)
• mkdocstrings-python
• pymdown-extensions

CLI Reference

usage: wj-mkdocs [-h] [--version] --config CONFIG --output OUTPUT --docs DOCS

wj-mkdocs: 1.0.1

Sets up environment variables to point to various internal resources that
MkDocs can then reference using `!ENV`. It then launches mkdocs.

options:
  -h, --help           show this help message and exit
  --version            show program's version number and exit
  --config, -f CONFIG  Provide a specific MkDocs config.
  --output, -o OUTPUT  The directory to output the result of the documentation
                       build.
  --docs, -d DOCS      Root folder containing MD files.