canonical/open-documentation-academy

Robotics: move the reference architecture page to Explanation

Aperta

#359 aperta il 22 lug 2026

 (2 commenti) (0 reazioni) (1 assegnatario)Python (99 fork)auto 404
diátaxisgood first issuesize 1

Metriche repository

Star
 (119 stelle)
Metriche merge PR
 (Metriche PR in attesa)

Descrizione

The mentor for this issue is @geoffreynyaga

Background

The Reference architecture page explains how parts of the Canonical Robotics stack fit together. Despite its name, it is explanatory content rather than reference material, so it belongs in the Explanation section under the Diátaxis documentation framework.

Prerequisites

Basic Git and Markdown knowledge is required. Familiarity with Sphinx documentation is helpful.

Task

  1. In the canonical/robotics_documentation repository, move docs/references/ref_architecture/reference_architecture.md to the Explanation section. Move its image with it as well.
  2. Remove the page from docs/references/index.md and add it to docs/explanations/index.md.
  3. Update the home-page link in docs/index.rst and any other internal links to use the new path.
  4. Add a redirect in docs/conf.py from the old URL to the new URL so existing links do not break.
  5. Run make clean and make linkcheck; both commands must pass.
  6. Open a pull request against the repository and sign the Canonical contributor license agreement.

Outcome

The Reference architecture page appears under Explanation, no longer appears under Reference, and the former URL redirects to its new location. Internal links and link checking pass.

Resources

Guida contributor