canonical / canonical/robotics_documentation
Update cross-references in Tutorials 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
Tutorial pages use relative Markdown links to other documentation pages. For example, in `docs/tutorials/observability/deploy-cos-for-robotics-agent-on-your-robot.md`, **Host a basic file server for your rosbags** links to `../../how-to-guides/operation/deploy-caddy.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/tutorials/` directory and its files.
## Task
1. Review documentation-page links in `docs/tutorials/` 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 Caddy page in the example above, use `(how-to-guides-operation-deploy-caddy)=`.
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 Tutorials 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)
* [Tutorials directory](https://github.com/canonical/robotics_documentation/tree/main/docs/tutorials)
Contributor guide
No contributing guide indexed for this repository
Research direction
Scan docs/tutorials/, starting with docs/tutorials/observability/deploy-cos-for-robotics-agent-on-your-robot.md and the MyST cross-referencing guide. Convert documentation-page relative links, add meaningful unique labels following the stated convention, then run make clean, make run, and make linkcheck; manually verify every changed link in the local site.
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