Skip to content

Documentation & Tooling

Practical guidance on maintaining the documentation site, using AI-assisted development, and handling recurring maintenance challenges.

Maintaining the Documentation (MkDocs)

The documentation site is built with MkDocs using the Material theme. Source files live in docs/ and the configuration is in mkdocs.yml.

Running the docs locally

pip install mkdocs mkdocs-material
mkdocs serve

Then open http://localhost:8000 to preview. The site rebuilds automatically on file changes.

Adding or renaming pages

  1. Create (or rename) a .md file under docs/.
  2. Add (or update) the corresponding entry in the nav: section of mkdocs.yml.
  3. Update any internal links that referenced the old path.

Logo, favicon, and branding

The Material theme logo and favicon are configured in mkdocs.yml:

theme:
  logo: logo.png

For full customization options see:

Custom CSS styles

The file docs/stylesheets/custom_styles.css overrides the Material theme's default palette and colors. It is loaded via:

extra_css:
  - stylesheets/custom_styles.css

For guidance on CSS customization:

Keeping docs in sync with code changes

Every code change that affects user-visible behavior, public API, or configuration should be accompanied by a documentation update. A practical checklist:

  • [ ] Does the change affect the user installation or configuration steps? → Update docs/user/installation.md or docs/user/configuration.md
  • [ ] Does the change affect public class/trait interfaces or method signatures? → Update docs/api/index.md
  • [ ] Does the change introduce a new pattern or architectural decision? → Update docs/developer/architecture.md or docs/developer/extending.md
  • [ ] Does the change affect how the CI pipeline works? → Update CI/CD Pipeline and docs/specs/GITLAB_PAGES_SPEC.md

Using AI for Development

AI tools (GitHub Copilot, ChatGPT, etc.) can accelerate development significantly. To make AI-generated code reliable and reviewable:

  • Store plans and specs in docs/specs/ — these markdown files provide AI with structured context about requirements, decisions, and rationale. See the AI & Dev Specs section for naming conventions and how to add new spec files.
  • Version the spec files in Git — just like code, so the history of decisions is preserved for future maintainers.
  • Name spec files clearly, e.g.:
  • docs/specs/GITLAB_PAGES_SPEC.md — documentation site planning
  • docs/specs/PLAN.md — general module development roadmap
  • Review AI output carefully — especially PHPStan level 9 and Drupal coding standards compliance, which AI models sometimes get wrong.
  • Keep specs updated after implementation so they reflect actual decisions, not just initial plans.

Common Maintenance Challenges

PHPStan at level 9

PHPStan is set to the maximum strictness level (_PHPSTAN_LEVEL: 9). This catches many real bugs but also means:

  • PHP or Drupal API changes in minor/patch releases can introduce new PHPStan errors even without any module code changes.
  • Type inference improvements in newer PHPStan versions may surface previously hidden issues.
  • Fixes: Add precise type annotations, adjust PHPStan baseline (phpstan.neon), or adapt code to match the stricter signature expectations.

PHPUnit deprecation warnings

As Drupal evolves, PHPUnit deprecates testing APIs. These surface as warnings that eventually become errors. Common triggers:

  • Changes to setUpBeforeClass() / tearDownAfterClass() signatures
  • Removal of assertion aliases (assertRegExp → assertMatchesRegularExpression)
  • Changes to getMockBuilder() API

Use #[IgnoreDeprecations] temporarily while Drupal still supports the old API, but schedule a follow-up to fix the underlying cause once support is dropped.

Keeping documentation current

Documentation drift — where docs fall behind the code — is one of the most common maintenance problems. Mitigate it by:

  • Treating documentation updates as part of the definition of done for every issue or MR
  • Using the checklist in the Keeping docs in sync section above
  • Reviewing all docs pages when preparing a new release

Maintainer Guide: Overview  ·  Getting Started  ·  CI/CD Pipeline  ·  Documentation & Tooling