Skip to content

Clarify best practices with ref target labels in docs #927

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

Open
CAM-Gerlach opened this issue Aug 3, 2022 · 0 comments
Open

Clarify best practices with ref target labels in docs #927

CAM-Gerlach opened this issue Aug 3, 2022 · 0 comments
Assignees
Labels
enhancement guide-new content Additions; New content or section needed

Comments

@CAM-Gerlach
Copy link
Member

On python/cpython#94636 , specifically python/cpython#94636 (comment) , @ezio-melotti , @erlend-aasland and I discussed that that it might be helpful to clarify in the devguide some additional guidance related to reference target labels in the Cross-linking markup section.

Specifically, it could mention that whenever possible, the existing ref target should be left place (either instead of or addition to adding a new one) when sections are changed or moved, since it ensures any inbound internal or Intersphinx references don't break or need to be changed, as well as any external links that anchor (provided that it wasn't moved to a different page without a redirection).

Also, it could provide a guideline and examples on how ref labels should be "namespaced" to avoid conflicts, i.e. by the module name for library docs, or the page name elsewhere, documenting existing (if not always consistent) convention.

If we agree this would be helpful, I can submit a PR on this once #916 is merged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement guide-new content Additions; New content or section needed
Projects
None yet
Development

No branches or pull requests

2 participants