build(docs): update Starter Pack and add passthrough to docs Makefile #478

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

medubelko merged 4 commits into canonical:main from medubelko:craft-4951-build-docs-passthrough

Jan 16, 2026

+1,798 −860

.prettierignore

medubelko marked this conversation as resolved.

Show resolved Hide resolved

Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		docs/.sphinx

.readthedocs.yaml

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -30,7 +30,7 @@ build:
  
        create_environment:

          - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"

        install:

          - make setup-docs UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}"

          - make setup-docs VENVDIR="${READTHEDOCS_VIRTUALENV_PATH}" UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}"

        build:

          html:

            - make docs UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" DOCS_OUTPUT="$READTHEDOCS_OUTPUT/html/"

            - make docs VENVDIR="${READTHEDOCS_VIRTUALENV_PATH}" UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" BUILDDIR="$READTHEDOCS_OUTPUT/html/"

common.mk

-Original file line number
+Diff line change
@@ Expand Up / @@ -2,8 +2,12 @@ @@
     # https://github.com/canonical/starbase
     SOURCES=$(wildcard *.py) $(PROJECT) tests
-    DOCS=docs
-    DOCS_OUTPUT=$(DOCS)/_build
+    # Env vars for the docs Starter Pack. They must be exported so make can pass them to the
+    # docs Makefile.
+    export BUILDDIR ?= _build
+    export VENVDIR ?= ../.venv
+    export VALEDIR ?= $(VENVDIR)/lib/python*/site-packages/vale
     ifneq ($(OS),Windows_NT)
     	OS := $(shell uname)
@@ Expand Down Expand Up @@
     	uv sync $(UV_TEST_GROUPS) $(UV_LINT_GROUPS) $(UV_DOCS_GROUPS)
     .PHONY: setup-docs
-    setup-docs: _setup-docs  ##- Set up a documentation-only environment
+    setup-docs: _setup-docs  ##- Set up the documentation environment
     	uv sync --no-dev $(UV_DOCS_GROUPS)
     .PHONY: _setup-docs
@@ Expand Down Expand Up / @@ -200,16 +204,9 @@ ifneq ($(CI),) @@
     	@echo ::endgroup::
     endif
+    # Legacy alias for linting docs
     .PHONY: lint-docs
-    lint-docs:  ##- Lint the documentation
-    ifneq ($(CI),)
-    	@echo ::group::$@
-    endif
-    	uv run $(UV_DOCS_GROUPS) sphinx-lint --ignore docs/reference/commands --ignore docs/_build --enable all $(DOCS) -d line-too-long,missing-underscore-after-hyperlink,missing-space-in-hyperlink
-    	uv run $(UV_DOCS_GROUPS) sphinx-build -b linkcheck -W $(DOCS) docs/_linkcheck
-    ifneq ($(CI),)
-    	@echo ::endgroup::
-    endif
+    lint-docs: docs-lint  ##- Lint the documenation
     .PHONY: lint-twine
     lint-twine: pack-pip  ##- Lint Python packages with twine
@@ Expand Down Expand Up / @@ -251,13 +248,70 @@ endif @@
     test-find-slow:  ##- Identify slow tests. Set cutoff time in seconds with SLOW_CUTOFF_TIME
     	uv run pytest --durations 0 --durations-min $(SLOW_CUTOFF_TIME)
+    # Alias for `html` target in docs project. We want to use our own `.venv`, so we
+    # replace it.
     .PHONY: docs
-    docs:  ## Build documentation
-    	uv run $(UV_DOCS_GROUPS) sphinx-build -b dirhtml -W $(DOCS) $(DOCS_OUTPUT)
+    docs: docs-install  ## Render the documentation to disk
+    	$(MAKE) -C docs html --no-print-directory
+    # Alias for `html` target in docs project
     .PHONY: docs-auto
-    docs-auto:  ## Build and host docs with sphinx-autobuild
-    	uv run --group docs sphinx-autobuild -b dirhtml --open-browser --port=8080 --watch $(PROJECT) -W $(DOCS) $(DOCS_OUTPUT)
+    docs-auto: docs-install  ##- Render the documentation in a live session
+    	$(MAKE) -C docs serve --no-print-directory
+    # Override for `install` target in docs project. We still need the Vale setup, so we
+    # run that after the parent docs setup.
+    .PHONY: docs-install
+    docs-install: setup-docs  ##- Set up documentation packages
+    	$(MAKE) -C docs vale-install --no-print-directory
+    # Alias for `setup-docs`
+    .PHONY: docs-setup
+    docs-setup: setup-docs
+    # Override for `clean` target in docs project. We don't want to touch `.venv`, so
+    # we pass a null dir instead.
+    .PHONY: docs-clean
+    docs-clean:  ##- Clean the temporary files used in documentation
+    	VENVDIR=null
+    	$(MAKE) -C docs clean --no-print-directory
+    # Override for `help` target in docs project
+    .PHONY: docs-help
+    docs-help:  ##- List the individual commands in the documentation subproject.
+    	@echo "Commands in the documentation subproject:"
+    	$(MAKE) -C docs help --no-print-directory
+    	@echo "Run these commands from inside the 'docs/' directory."
+    # Override for `pymarkdownlnt-install` target in docs project. Make it a noop.
+    .PHONY: docs-pymarkdownlnt-install
+    docs-pymarkdownlnt-install:
+    	@echo "Cannot run 'docs-pymarkdownlnt'. This project doesn't use Markdown."
+    # Override for `lint-md` target in docs project. Make it a noop.
+    .PHONY: docs-lint-md
+    docs-lint-md:
+    	@echo "Cannot run 'docs-lint-md'. This project doesn't use Markdown."
+    # Passthrough for the rest of the targets in docs project
+    .PHONY: docs-%
+    docs-%: docs-install
+    	$(MAKE) -C docs $(@:docs-%=%) --no-print-directory
+    # Run our own docs linting, then pass to the docs
+    .PHONY: docs-lint
+    docs-lint: docs  ##- Lint the documentation
+    ifneq ($(CI),)
+    	@echo ::group::$@
+    endif
+    	uv run $(UV_DOCS_GROUPS) sphinx-lint --ignore docs/reference/commands --ignore docs/_build --enable all docs -d line-too-long,missing-underscore-after-hyperlink,missing-space-in-hyperlink
+    	$(MAKE) -C docs spelling --no-print-directory
+    	$(MAKE) -C docs vale --no-print-directory
+    	$(MAKE) -C docs woke --no-print-directory
+    	$(MAKE) -C docs linkcheck --no-print-directory
+    ifneq ($(CI),)
+    	@echo ::endgroup::
+    endif
     .PHONY: pack-pip
     pack-pip:  ##- Build packages for pip (sdist, wheel)
@@ Expand Down @@

docs/.custom_wordlist.txt

-Original file line number
+Diff line change
@@ -0,0 +1,73 @@
+    # Leave a blank line at the end of this file to support concatenation
+    backend
+    backends
+    Canonical('s)?
+    Charmcraft
+    cjk
+    cryptographically
+    docstrings?
+    dvipng
+    fonts
+    freefont
+    Furo
+    github
+    GitHub
+    GPG
+    gyre
+    html
+    https
+    Intersphinx
+    io
+    ip
+    landscape
+    lang
+    lastmod
+    LaTeX
+    latexmk
+    Makefile
+    Multipass
+    MyST
+    Numpy
+    Open Graph
+    openapi
+    otf
+    PDF
+    plantuml
+    PNG
+    PR
+    Pygments
+    pymarkdown
+    QEMU
+    Read the Docs
+    readthedocs
+    reStructuredText
+    retrigger(ing)?
+    Rockcraft
+    rst
+    sequenceDiagram
+    sitemapindex
+    Sphinx
+    Spread
+    spread_test_example
+    Starcraft
+    subproject
+    subprojects
+    SVG
+    tex
+    texlive
+    TOC
+    toctree
+    txt
+    uncomment(ing)?
+    URL
+    utils
+    VMs
+    WCAG
+    whitespace
+    whitespaces
+    wordlist
+    xetex
+    xindy
+    xml
+    yaml
+    YouTube

docs/.gitignore

-Original file line number
+Diff line change
@@ -0,0 +1,26 @@
+    # Environment
+    *env*/
+    .sphinx/venv/
+    # Sphinx
+    .sphinx/warnings.txt
+    .sphinx/.wordlist.dic
+    .sphinx/.doctrees/
+    .sphinx/update/
+    .sphinx/node_modules/
+    # Vale
+    .sphinx/styles/*
+    .sphinx/vale.ini
+    # Build outputs
+    _build
+    # Node.js
+    package*.json
+    # Unrelated cache and config files
+    .DS_Store
+    __pycache__
+    .idea/
+    .vscode/

docs/.sphinx/.pre-commit-config.yaml

-Original file line number
+Diff line change
@@ -0,0 +1,23 @@
+    repos:
+      - repo: local
+        hooks:
+          - id: make-spelling
+            name: Run make spelling
+            entry: make -C docs spelling
+            language: system
+            pass_filenames: false
+            files: ^docs/.*\.(rst|md|txt)$
+          - id: make-linkcheck
+            name: Run make linkcheck
+            entry: make -C docs linkcheck
+            language: system
+            pass_filenames: false
+            files: ^docs/.*\.(rst|md|txt)$
+          - id: make-woke
+            name: Run make woke
+            entry: make -C docs woke
+            language: system
+            pass_filenames: false
+            files: ^docs/.*\.(rst|md|txt)$

docs/.sphinx/.pymarkdown.json

-Original file line number
+Diff line change
@@ -0,0 +1,46 @@
+    {
+      "plugins": {
+        "selectively_enable_rules": true,
+        "heading-style": {
+          "enabled": true,
+          "style": "atx"
+        },
+        "commands-show-output": {
+          "enabled": true
+        },
+        "no-missing-space-atx": {
+          "enabled": true
+        },
+        "blanks-around-headings": {
+          "enabled": true
+        },
+        "heading-start-left": {
+          "enabled": true
+        },
+        "no-trailing-punctuation": {
+          "enabled": true,
+          "punctuation": ".,;。，；"
+        },
+        "blanks-around-fences": {
+          "enabled": true,
+          "list_items": false
+        },
+        "blanks-around-lists": {
+          "enabled": true
+        },
+        "hr-style": {
+          "enabled": true
+        },
+        "no-empty-links": {
+          "enabled": true
+        },
+        "no-alt-text": {
+          "enabled": true
+        }
+      },
+      "extensions": {
+        "front-matter": {
+          "enabled": true
+        }
+      }
+    }

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

build(docs): update Starter Pack and add passthrough to docs Makefile #478

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!