canonical / canonical/robotics_documentation

Update cross-references in Tutorials to MyST standards

Open
#151 0 comments 0 reactions 0 assignees View on GitHub
CODA
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.