Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Copy Oliver's label advice from chat. #681

Merged
merged 1 commit into from
Jan 31, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,33 @@ to via intersphinx.
We use a few custom Sphinx extensions, for details see
[cylc-sphinx-extensions](https://cylc.github.io/cylc-sphinx-extensions/).


### Label Guidance

Some things to bear in mind when defining labels in cylc-doc e.g. `.. _my-label`:

**Namespace your labels**

* E.g. `user-guide.something` rather than `something`.
* (Look for existing naming patterns before defining a new one).

**Labels are imported from other projects (e.g. Rose, Jupyter Server, etc)**
* So avoid excessively vague labels where possible.
* And only add labels where they are needed (labels are only for references,
they don't serve any other purpose so adding excess ones doesn't benefit
other things).

**References resolve attach headers**
* So if a section has the heading `Running Schedulers`, then a good label
might be `user-guide.running-schedulers` rather than `scheduler runtime`
as this gives the person using the label a better idea of how it is
likely to be presented.

**Labels are forever**
* Other projects (e.g. metomi-docs) might use these labels!



## Development

[![test](https://github.com/cylc/cylc-doc/workflows/test/badge.svg?branch=master&event=push)](https://github.com/cylc/cylc-doc/actions?query=workflow%3Atest)
Expand Down
Loading