docs/sphinx_overrides — content-ownership policy

This directory is staged on top of the vendored vendor/Ralph-Workflow Sphinx source (see lib/tasks/docs.rake#stage_sphinx_sources) before every docs build. It is Ralph-Site’s layer of the docs pipeline, and it owns:

  • Sphinx configuration — conf.py

  • Theme — _themes/ralph-docs/

  • Static assets — _static/

  • Site-only pages — marketing/SEO pages that do not exist upstream (comparison pages, use-case routing pages, the site’s own docs landing page, etc.)

The rule

An entry in this directory must never share a filename with an upstream docs/sphinx/<name> page. Ralph-Site is free to build its own pages, but it may not silently overwrite or shadow Ralph Workflow’s own documentation content — doing so causes production to serve stale or diverged prose under an identity readers (and make serve-docs in the upstream package) believe is the canonical page.

This is enforced at build time: docs:build calls assert_no_upstream_content_shadow! before staging the overlay, and aborts the build if any non-exempt entry here collides with an upstream filename. Run bin/rails docs:verify_no_upstream_shadow for a standalone check. Both are wired into DocsDeployPreparation::PREPARE_COMMANDS, so a colliding override can never reach a deploy.

The only entries exempt from this check are conf.py, _static/, and _themes/ — theming/config surfaces Ralph-Site is meant to own outright.

If you need a site-specific version of an upstream page

Do not name the override file after the upstream page. Instead:

  1. Give the override a distinct filename (e.g. the site’s docs landing page lives at site-home.rst, not index.rst — see the root_doc comment in conf.py).

  2. Wire it into navigation via :doc: references / toctrees from site-home.rst or another site-owned page.

  3. If the new page needs to occupy a URL an upstream page would otherwise claim (as site-home.rst does for /docs/), relocate the build output post-render in lib/tasks/docs.rake#task build rather than the source pre-render — see the SITE_LANDING_PAGE / RELOCATED_UPSTREAM_LANDING_PAGE handling there. The upstream page still ships, unmodified, just at a different URL (/docs/manual) instead of being deleted.

That way the upstream page’s actual content is never edited, replaced, or hidden — only, at most, relocated to a non-colliding URL — and docs:verify_no_upstream_shadow stays green.