Skip to content

Docs: Use "Sentence case" for titles #10055

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

Merged

Conversation

benjaoming
Copy link
Contributor

@benjaoming benjaoming commented Feb 21, 2023

@ericholscher This is supposed to be a 100% neutral change. No discussions of titles intended. Just want to get sentence case introduced and move on to creating new sub-levels in the next PR...

  • Go through all titles
  • Go through all "How to do x" titles
  • Navigation labels for all "How to do x" titles...
  • Go through all references like :doc: and :ref: that has a "Title Case" reference

📚 Documentation previews 📚

@benjaoming benjaoming added Improvement Minor improvement to code Needed: documentation Documentation is required labels Feb 21, 2023
@benjaoming
Copy link
Contributor Author

I'm investigating why I'm getting a lot of undefined label warnings.

The build of this PR is broken for good reasons.

But for instance this build (where we merged all the Diátaxis changes) did not fail, although it contained the same broken references.

Example:

/home/docs/checkouts/readthedocs.org/user_builds/docs/checkouts/10055/docs/user/analytics.rst:22: WARNING: undefined label: 'server-side-search/index:search analytics'

server-side-search/index:search analytics clearly doesn't exist. But it wasn't refactored in this PR.

This means that this page currently contains a broken anchor link:

https://docs.readthedocs.io/en/stable/analytics.html

@benjaoming
Copy link
Contributor Author

A quick pattern for ack to find all occurrences of title case :doc: and :ref:

ag -I ":doc:\`\\p{Lu}\pL+\s\\p{Lu}"
ag -I ":ref:\`\\p{Lu}\pL+\s\\p{Lu}"

@benjaoming benjaoming marked this pull request as ready for review February 24, 2023 15:11
@benjaoming benjaoming requested a review from a team as a code owner February 24, 2023 15:11
@benjaoming benjaoming changed the title Use "Sentence case" for titles Docs: Use "Sentence case" for titles Feb 24, 2023
Copy link
Member

@ericholscher ericholscher left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simple enough 👍

@benjaoming benjaoming merged commit 8c9b759 into readthedocs:main Feb 24, 2023
@benjaoming benjaoming deleted the diataxis/sentence-case-and-how-to branch February 24, 2023 15:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Improvement Minor improvement to code Needed: documentation Documentation is required
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants