canonical / canonical/robotics_documentation
Update cross-references in Reference to MyST standards
- Dominant language
- No language data
- Stars
- 1
- Forks
- 5
- Avg merge
- 14d 23h
- Merged PRs (30d)
- 1
Description
The mentor for this issue is @geoffreynyaga
## Background
Reference pages use relative Markdown links to other documentation pages. For example, in `docs/references/workshop/ros2-minimal-sdk.md`, **ROS 2 development using Workshop** links to `../../tutorials/workshop/ros2-dev-workshop.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/references/` and its subdirectories.
## Task
1. Review documentation-page links in `docs/references/` that use relative paths. Do not convert image or other asset paths.
2. Replace each relative documentation link with a [MyST reference](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html). 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 Workshop page in the example above, use `(tutorials-workshop-getting-started)=`.
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](https://ubuntu.com/legal/contributors).
## Outcome
Documentation-page links in Reference use MyST references, their anchors follow a consistent convention, and all changed links have been manually verified.
## Resources
* [MyST-Parser cross-referencing](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html)
* [Reference directory](https://github.com/canonical/robotics_documentation/tree/main/docs/references)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with docs/references/workshop/ros2-minimal-sdk.md and the MyST cross-referencing guide, then audit relative documentation links throughout docs/references/ without changing asset paths. Add and review the required labels and verify each changed link in the local site after running make clean and make run. Done means all changed links reach the intended page or section and make linkcheck passes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100