generate-docs

generate-docs#

The generate-docs command automates the creation of a “Living Specification” by converting your Gherkin feature files into ReStructuredText (.rst) for Sphinx processing.

Important

This command is designed to be destructive within the target directory. It creates a complete snapshot of your current features, ensuring that deleted feature files are removed from the documentation.

Usage#

argobeast generate-docs [options]

Arguments#

Option

Description

-y, --yes

Skip the interactive confirmation prompt. This is strictly required for CI/CD pipelines to prevent the build from hanging.

How It Works#

When executed, this command performs the following operations:

  1. Scan: Recursively walks through the ./features directory.

  2. Parse: Uses behave.parser to read scenarios, steps, and tags.

  3. Generate: Creates individual .rst files in ./docs/source/beast_docs/.

  4. Index: Generates a dynamic index.rst to link all features into the Sphinx Table of Contents.

Generated Output Format#

The command injects a “Level 1 Defense” header into every generated file. This is a comment block warning human readers (and developers) that manual edits to the file will be overwritten during the next build.

Example Output (RST):

.. ---------------------------------------------------------------------------
..  ⚠️  AUTO-GENERATED FILE - DO NOT EDIT MANUALLY  ⚠️
..
..  This file was generated by ArgoBEAST on 2026-01-19.
.. ---------------------------------------------------------------------------

Feature Name
============

**Tags:** ``@smoke``, ``@login``

Scenario Name
-------------

.. list-table::
   :widths: 10 90

   * - **Given**
     - I am on the login page
   * - **When**
     - I enter valid credentials

CI/CD Integration#

To ensure your documentation is always up to date with your test suite, add this command to your deployment pipeline before the Sphinx build command.

# Example GitHub Actions step
- name: Generate Living Specs
  run: |
    pip install -r requirements.txt
    argobeast generate-docs -y
    make html