docs(feat): Add docs justfile for Sphinx automation

why: Provide dedicated task runner for documentation builds with proper port configuration. what: - Add docs/justfile for Sphinx build targets - Configure HTTP port to 8031 for development server - Include watch, serve, and autobuild recipes
tmux-python · tony · Dec 27, 2025 · Dec 27, 2025 · Dec 27, 2025 · Dec 27, 2025
commit 5870c5310594272ee397e59bcab1da432f17eaa2
diff --git a/docs/justfile b/docs/justfile
@@ -0,0 +1,191 @@
+# justfile for tmuxp documentation
+# https://just.systems/
+
+set shell := ["bash", "-uc"]
+
+# Configuration
+http_port := "8031"
+builddir := "_build"
+sphinxopts := ""
+sphinxbuild := "uv run sphinx-build"
+sourcedir := "."
+
+# File patterns for watching
+watch_files := "find .. -type f -not -path '*/\\.*' | grep -i '.*[.]\\(rst\\|md\\)$\\|.*[.]py$\\|CHANGES\\|TODO\\|.*conf\\.py' 2> /dev/null"
+
+# Sphinx options
+allsphinxopts := "-d " + builddir + "/doctrees " + sphinxopts + " ."
+
+# List all available commands
+default:
+    @just --list
+
+# ============================================================================
+# Build targets
+# ============================================================================
+
+# Build HTML documentation
+html:
+    {{ sphinxbuild }} -b html {{ allsphinxopts }} {{ builddir }}/html
+    @echo ""
+    @echo "Build finished. The HTML pages are in {{ builddir }}/html."
+
+# Clean build directory
+clean:
+    rm -rf {{ builddir }}/*
+
+# Build directory HTML files
+dirhtml:
+    {{ sphinxbuild }} -b dirhtml {{ allsphinxopts }} {{ builddir }}/dirhtml
+    @echo ""
+    @echo "Build finished. The HTML pages are in {{ builddir }}/dirhtml."
+
+# Build single HTML file
+singlehtml:
+    {{ sphinxbuild }} -b singlehtml {{ allsphinxopts }} {{ builddir }}/singlehtml
+    @echo ""
+    @echo "Build finished. The HTML page is in {{ builddir }}/singlehtml."
+
+# Build EPUB
+epub:
+    {{ sphinxbuild }} -b epub {{ allsphinxopts }} {{ builddir }}/epub
+    @echo ""
+    @echo "Build finished. The epub file is in {{ builddir }}/epub."
+
+# Build LaTeX files
+latex:
+    {{ sphinxbuild }} -b latex {{ allsphinxopts }} {{ builddir }}/latex
+    @echo ""
+    @echo "Build finished; the LaTeX files are in {{ builddir }}/latex."
+
+# Build PDF via LaTeX
+latexpdf:
+    {{ sphinxbuild }} -b latex {{ allsphinxopts }} {{ builddir }}/latex
+    @echo "Running LaTeX files through pdflatex..."
+    make -C {{ builddir }}/latex all-pdf
+    @echo "pdflatex finished; the PDF files are in {{ builddir }}/latex."
+
+# Build plain text files
+text:
+    {{ sphinxbuild }} -b text {{ allsphinxopts }} {{ builddir }}/text
+    @echo ""
+    @echo "Build finished. The text files are in {{ builddir }}/text."
+
+# Build man pages
+man:
+    {{ sphinxbuild }} -b man {{ allsphinxopts }} {{ builddir }}/man
+    @echo ""
+    @echo "Build finished. The manual pages are in {{ builddir }}/man."
+
+# Build JSON output
+json:
+    {{ sphinxbuild }} -b json {{ allsphinxopts }} {{ builddir }}/json
+    @echo ""
+    @echo "Build finished; now you can process the JSON files."
+
+# Build HTML help files
+htmlhelp:
+    {{ sphinxbuild }} -b htmlhelp {{ allsphinxopts }} {{ builddir }}/htmlhelp
+    @echo ""
+    @echo "Build finished; now you can run HTML Help Workshop with the .hhp project file in {{ builddir }}/htmlhelp."
+
+# Build Qt help files
+qthelp:
+    {{ sphinxbuild }} -b qthelp {{ allsphinxopts }} {{ builddir }}/qthelp
+    @echo ""
+    @echo "Build finished; now you can run 'qcollectiongenerator' with the .qhcp project file in {{ builddir }}/qthelp."
+
+# Build Devhelp files
+devhelp:
+    {{ sphinxbuild }} -b devhelp {{ allsphinxopts }} {{ builddir }}/devhelp
+    @echo ""
+    @echo "Build finished."
+
+# Build Texinfo files
+texinfo:
+    {{ sphinxbuild }} -b texinfo {{ allsphinxopts }} {{ builddir }}/texinfo
+    @echo ""
+    @echo "Build finished. The Texinfo files are in {{ builddir }}/texinfo."
+
+# Build Info files from Texinfo
+info:
+    {{ sphinxbuild }} -b texinfo {{ allsphinxopts }} {{ builddir }}/texinfo
+    @echo "Running Texinfo files through makeinfo..."
+    make -C {{ builddir }}/texinfo info
+    @echo "makeinfo finished; the Info files are in {{ builddir }}/texinfo."
+
+# Build gettext catalogs
+gettext:
+    {{ sphinxbuild }} -b gettext {{ sphinxopts }} . {{ builddir }}/locale
+    @echo ""
+    @echo "Build finished. The message catalogs are in {{ builddir }}/locale."
+
+# ============================================================================
+# Validation
+# ============================================================================
+
+# Check all external links
+linkcheck:
+    {{ sphinxbuild }} -b linkcheck {{ allsphinxopts }} {{ builddir }}/linkcheck
+    @echo ""
+    @echo "Link check complete; look for any errors in the above output or in {{ builddir }}/linkcheck/output.txt."
+
+# Run doctests embedded in documentation
+doctest:
+    {{ sphinxbuild }} -b doctest {{ allsphinxopts }} {{ builddir }}/doctest
+    @echo "Testing of doctests in the sources finished, look at the results in {{ builddir }}/doctest/output.txt."
+
+# Check build from scratch
+checkbuild:
+    rm -rf {{ builddir }}
+    {{ sphinxbuild }} -n -q ./ {{ builddir }}
+
+# Build redirects configuration
+redirects:
+    {{ sphinxbuild }} -b rediraffewritediff {{ allsphinxopts }} {{ builddir }}/redirects
+    @echo ""
+    @echo "Build finished. The redirects are in rediraffe_redirects."
+
+# Show changes overview
+changes:
+    {{ sphinxbuild }} -b changes {{ allsphinxopts }} {{ builddir }}/changes
+    @echo ""
+    @echo "The overview file is in {{ builddir }}/changes."
+
+# ============================================================================
+# Development
+# ============================================================================
+
+# Watch files and rebuild on change
+watch:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if command -v entr > /dev/null; then
+        ${{ watch_files }} | entr -c just html
+    else
+        just html
+    fi
+
+# Serve documentation via Python http.server
+serve:
+    @echo '=============================================================='
+    @echo ''
+    @echo 'docs server running at http://localhost:{{ http_port }}/'
+    @echo ''
+    @echo '=============================================================='
+    python -m http.server {{ http_port }} --directory {{ builddir }}/html
+
+# Watch and serve simultaneously
+dev:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    just watch &
+    just serve
+
+# Start sphinx-autobuild server
+start:
+    uv run sphinx-autobuild "{{ sourcedir }}" "{{ builddir }}" {{ sphinxopts }} --port {{ http_port }}
+
+# Design mode: watch static files and disable incremental builds
+design:
+    uv run sphinx-autobuild "{{ sourcedir }}" "{{ builddir }}" {{ sphinxopts }} --port {{ http_port }} --watch "." -a