canonical/open-documentation-academy

Robotics: update cross-references in Explanation to MyST standards

开放

#363 创建于 2026年7月22日

 (0 条评论) (0 个反应) (0 位负责人)Python (99 个派生)auto 404
explanationgood first issuesize 3

仓库指标

星标
 (119 个星标)
PR 合并指标
 (PR 指标待抓取)

描述

The mentor for this issue is @geofreynyaga

Background

Explanation pages use relative Markdown links to other documentation pages. For example, in docs/explanations/snaps/ros-architectures-with-snaps.md, addition of an extra interface links to ../../how-to-guides/packaging/ros-2-shared-memory-in-snaps.md. Replace these with MyST references so links are resilient to file moves and use meaningful page or section anchors.

Scope is limited to docs/explanations/ and its subdirectories.

Task

  1. Review documentation-page links in docs/explanations/ that use relative paths. Do not convert image or other asset paths.
  2. Replace each relative documentation link with a MyST reference. Use a page's level-1 heading when the link is to the whole page; otherwise, reference the relevant section heading.
  3. Add labels where required. For level-1 headings, use the folder-subfolder-title-slug convention, with concise, unique lowercase slugs; for the linked shared-memory page in the example above, use (how-to-guides-packaging-ros-2-shared-memory)=.
  4. Check every new or changed label manually: it must be meaningful, unique, and follow the convention.
  5. Run make clean, then make run. In the local site, manually click every changed link and confirm it reaches the intended page or section.
  6. Run make linkcheck; it must pass.
  7. Open a pull request against the repository and sign the Canonical contributor license agreement.

Outcome

Documentation-page links in Explanation use MyST references, their anchors follow a consistent convention, and all changed links have been manually verified.

Resources

贡献者指南