canonical / canonical/robotics_documentation

Update cross-references in How-to guides to MyST standards

Open
#153 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

How-to guides use relative Markdown links to other documentation pages. For example, in `docs/how-to-guides/development/ros2-git.md`, **Workshop basics** 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/how-to-guides/` and its subdirectories.

## Task

1. Review documentation-page links in `docs/how-to-guides/` 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 How-to guides 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)
* [How-to guides directory](https://github.com/canonical/robotics_documentation/tree/main/docs/how-to-guides)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing relative documentation links under docs/how-to-guides/, using docs/how-to-guides/development/ros2-git.md and the MyST-Parser cross-referencing guide as references. Exclude image and asset paths, then run make clean, make run, and make linkcheck. Done means every changed documentation link reaches the intended page or section, labels are meaningful and unique, and 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.