Why This Matters

Code docs decay because they're manual. A generator that extracts comments, generates markdown, and builds a site keeps docs fresh with zero manual effort.

Concept Explained

A script that walks src/, extracts docstrings/JSDoc, generates markdown per module, builds a static site (MkDocs, Docusaurus, or similar).

How It Works

Walk src/. For each file, extract docstrings. Generate markdown with function signatures, docstrings, and source links. Build static site. Deploy via CI.

Step-by-Step Tutorial

1. Walk source

2. Extract docstrings

3. Generate markdown

4. Build static site

5. Deploy via CI

Real-World Example

A team built a docs-site generator. Every commit regenerated the docs site. New hires could browse API docs, architecture, and examples without reading source. Onboarding time dropped 30%.

Example Prompts / Commands / Code

#!/usr/bin/env python3
# generate-docs.py
import ast
import os
from pathlib import Path

SRC_DIR = 'src'
DOCS_DIR = 'docs/api'

for py_file in Path(SRC_DIR).rglob('*.py'):
    module_name = py_file.stem
    docs_file = Path(DOCS_DIR) / f'{module_name}.md'

    with open(py_file) as f:
        tree = ast.parse(f.read())

    content = [f'# {module_name}\n']

    for node in ast.walk(tree):
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            docstring = ast.get_docstring(node) or 'No documentation.'
            sig = f'def {node.name}({ast.arguments(args=node.args)})'
            content.append(f'## `{node.name}`\n')
            content.append(f'```python\n{sig}\n```\n')
            content.append(f'{docstring}\n')

    docs_file.parent.mkdir(parents=True, exist_ok=True)
    docs_file.write_text('\n'.join(content))

print('Docs generated. Run: mkdocs build')

# .github/workflows/docs.yml
name: Build Docs
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python3 generate-docs.py
      - run: pip install mkdocs && mkdocs build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

Common Mistakes

• Generating without filtering — internal/private functions exposed.
• No CI automation — docs decay.
• Not linking to source — readers can't verify.
• Forgetting to deploy — site never updates.

Best Practices

• Filter: only public functions in docs.
• Automate via CI on every commit.
• Link to source (file:line).
• Deploy automatically (GitHub Pages).
• Measure onboarding improvement.

Troubleshooting

Practical Exercise

Professional Challenge

Frequently Asked Questions

Further Reading

• MkDocs
• Docusaurus

Official References

• MkDocs

Related lessons: BE-24, BE-47