Build Your Python Project Documentation With MkDocs¶

This repository is set up so its documentation can be built as a static site and deployed to GitHub Pages.

The goal is simple:

write normal Markdown files
keep user and developer docs in one place
let GitHub Actions build and publish the site

Why MkDocs Fits This Project¶

MkDocs is a good match here because:

the project already has structured Markdown
the documentation is mostly conceptual and procedural
we want a simple GitHub Pages deployment path
we want separate sections for users and developers without building a large Sphinx extension stack

Files Added For The Docs Site¶

`mkdocs.yml`¶

Source: mkdocs.yml

This file defines:

site metadata
navigation
theme
markdown features

`docs/requirements.txt`¶

Source: docs/requirements.txt

This keeps the docs build dependencies explicit:

mkdocs
mkdocs-material

Markdown Pages¶

Examples:

docs/index.md
docs/getting-started.md
docs/user-guide/plot2insights.md
docs/developer-guide/framework-architecture.md

Build Locally¶

From the repository root:

python3 -m venv .venv-docs
source .venv-docs/bin/activate
pip install -r docs/requirements.txt
mkdocs serve

For a production-style build:

mkdocs build

This creates the static site under site/.

Deploy To GitHub Pages¶

The simplest stable approach is to deploy the generated static site through GitHub Actions.

1. Enable Pages In The Repository¶

In GitHub repository settings:

open Settings
open Pages
choose Build and deployment
set Source to GitHub Actions

2. Add A Docs Workflow¶

Create:

.github/workflows/docs.yml

Recommended workflow:

name: docs

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - uses: actions/configure-pages@v5
      - run: pip install -r docs/requirements.txt
      - run: mkdocs build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

3. Push To `main`¶

Once the workflow exists and Pages source is configured to GitHub Actions, pushing to main will publish the site.

How This Helps Both Audiences¶

For Users¶

You can expose:

installation instructions
command usage
layout selection
custom R script usage

For Developers¶

You can expose:

architecture
framework conventions
command patterns
scenario app examples

This is especially useful in this repository because the command modules are already strong framework references.

Why These Commands Make Good Developer Docs¶

These three files are not just CLI entrypoints. They are examples of how to productize the framework:

in_sight/commands/cf2insights.py
in_sight/commands/plot2insights.py
in_sight/commands/scrna2insights.py

That is why the docs site includes both:

user-facing command pages
developer-facing framework pages

Keep The Docs Practical¶

For this project, the best documentation style is:

short pages
real command examples
direct links to implementation files
clear separation between generic framework behavior and scenario-specific application behavior