MkDocs Usage

This guide explains how to install MkDocs locally, serve the documentation site, and regenerate action-specific pages.

Installation

1. Ensure Python 3.11+ is available (python3 --version).
2. Create a virtual environment at the repo root:

   python3 -m venv .venv
   

3. Activate the virtual environment:

   source .venv/bin/activate
   

4. Install MkDocs and the Material theme:

   pip install --upgrade pip
   pip install mkdocs mkdocs-material
   

Serving the Site

1. With the virtual environment activated, run:

   .venv/bin/python -m mkdocs serve
   

2. MkDocs serves the site at http://127.0.0.1:8000/ and watches for file changes.
3. Inside VS Code you can invoke the Serve MkDocs task, which runs the same command with the workspace as the working directory.

Regenerating Action Docs

Action reference pages (e.g., docs/actions/discord-notify.md) are generated from their corresponding actions/*/action.yml files using scripts/Modules/Utilities/Documentation/generate_action_docs.py.

1. Make sure the virtual environment (or a Python 3 interpreter) is available.
2. Run the generator, pointing it to the source action and desired Markdown output: bash python3 scripts/Modules/Utilities/Documentation/generate_action_docs.py \ --action actions/discord-notify/action.yml \ --output docs/actions/discord-notify.md
3. The script overwrites the auto-generated header and inputs table while preserving any content outside the <!-- AUTOGENERATED:ACTION-DOC --> markers (e.g., manual usage sections).
4. Re-run the command whenever action.yml changes so the docs stay in sync.

Using the PowerShell Wrapper

Prefer the PowerShell cmdlet when you already have the d-flows modules imported (e.g., within CI scripts or VS Code tasks):

1. Import the module:

   Import-Module ".\scripts\Modules\Utilities\Emojis\Emojis.psd1"
   Import-Module ".\scripts\Modules\Utilities\Colors\Colors.psd1"
   Import-Module ".\scripts\Modules\Utilities\MessageUtils\MessageUtils.psd1"
   Import-Module ".\scripts\Modules\Utilities\RepositoryUtils\RepositoryUtils.psd1"
   Import-Module ".\scripts\Modules\Utilities\Documentation\ActionDocs.psd1"
   

2. Invoke the generator for a single action:

   Invoke-ActionDoc `
     -ActionPath "actions/discord-notify/action.yml" `
     -OutputPath "docs/actions/discord-notify.md"
   

3. Use Invoke-AllActionDocs to regenerate every action documentation file in one go:

   Invoke-AllActionDocs
   

4. The cmdlets auto-detect the repository root, log progress with emojis, and surface errors if Python or the action file is missing. Use -PythonExecutable to target a custom interpreter if needed.