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.

Sign up for GitHub

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

Jump to bottom

Doc/#1274 Standardize letter case in titles and headers #1277

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

Doc/#1274 Standardize letter case in titles and headers #1277

wants to merge 3 commits into from

Conversation

arcanaxion
Copy link
Contributor

@arcanaxion arcanaxion commented Feb 6, 2025 •
edited
Loading

#1274

Hi, I took a quick pass to standardize the letter case in titles and headers. I opted for the following style rules, which made sense and minimized the needed changes to achieve consistency:

  1. Navigation item titles (in mkdocs.yml) are in sentence case. Some exceptions for higher level section items, e.g. "User Manual" and "Visual Elements".
  2. Page front matter // metadata are in title case.

I added these conventions to CONTIBUTING.md.

Notes:

  1. I also skimmed through some pages and standardized headers to either title case or sentence case (whichever was more common in that particular page). I don't think we should enforce a specific style here -- IMO different styles may have some semantic meaning more suitable for that page, so I would leave it to the author to decide and be consistent.
  2. "Sentence case" and "title case" may have different interpretations/implementations, e.g. APA, AP, etc. I'm no expert, so I wasn't too pedantic about this and did whatever made sense.

FabienLelaquais
FabienLelaquais requested changes Feb 10, 2025
View reviewed changes
Copy link
Member

@FabienLelaquais FabienLelaquais left a comment

Choose a reason for hiding this comment

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

Thanks!

docs/gallery/articles/drift_detection/index.md
@@ -36,7 +36,7 @@ categorical).

![Pipeline](images/drift-detection-pipeline.png){width=90% : .tp-image-border }

# How to use the Application
# How to Use the Application
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
# How to Use the Application
# How to use the application

docs/gallery/articles/face_recognition/index.md
@@ -22,7 +22,7 @@ This one page demo provides real-time face detection capabilities
thanks to the robust [OpenCV library](https://opencv.org/).


## How to use the Application
## How to Use the Application
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
## How to Use the Application
## How to use the application

docs/gallery/articles/production_planning/index.md
@@ -87,7 +87,7 @@ Results can be displayed as time series or pie charts, and different
graphs can be selected by choosing the data to display (costs, productions, etc.).


### Editing parameters
### Editing Parameters
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
### Editing Parameters
### Editing parameters

... 'Scenario' being a Taipy notion, I understand the capital in the previous case.
Not here.

docs/gallery/articles/tweet_generation/index.md
@@ -35,7 +35,7 @@ This application highlights several key features:

![Tweet Generation](images/tweet-generation.png){width=90% : .tp-image-border }

# How to generate Tweets
# How to Generate Tweets
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
# How to Generate Tweets
# How to generate tweets

Unless that's explicitly targeting Tweeter.

docs/tutorials/articles/using_tables/index.md
@@ -1,5 +1,5 @@
---
title: Using tables
title: Using Tables
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
title: Using Tables
title: Using tables

docs/tutorials/articles/version_management/index.md
@@ -1,5 +1,5 @@
---
title: Application versions with Git
title: Application Versions with Git
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
title: Application Versions with Git
title: Application versions with Git

mkdocs.yml_template
@@ -266,8 +266,8 @@ nav:
- "LLM":
- "LLM": gallery/llm/index.md
- "LLM Chatbot" : gallery/articles/chatbot/index.md
- "Vision ChatBot": gallery/articles/vision_chatbot/index.md
- "RAG ChatBot": gallery/articles/rag_chatbot/index.md
- "Vision Chatbot": gallery/articles/vision_chatbot/index.md
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
- "Vision Chatbot": gallery/articles/vision_chatbot/index.md
- "Vision chatbot": gallery/articles/vision_chatbot/index.md

mkdocs.yml_template
- "Vision ChatBot": gallery/articles/vision_chatbot/index.md
- "RAG ChatBot": gallery/articles/rag_chatbot/index.md
- "Vision Chatbot": gallery/articles/vision_chatbot/index.md
- "RAG Chatbot": gallery/articles/rag_chatbot/index.md
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
- "RAG Chatbot": gallery/articles/rag_chatbot/index.md
- "RAG chatbot": gallery/articles/rag_chatbot/index.md

@FabienLelaquais FabienLelaquais added 📈 Improvement Improvement of a feature. 📄 Documentation Internal or public documentation 🟧 Priority: High Stalls work on the project or its dependents labels Feb 10, 2025
@arcanaxion
Copy link
Contributor Author

@FabienLelaquais Thanks for reviewing. I agree with the lower case "tweet" and rewriting to "Visual Elements for Scenario Management" header for clarity.

The other changes are clashing with the notes in my post.

Before I accept the other changes, let's decide on a style and I'll make the changes to all pages accordingly. At the moment, my implementation was that:

  1. Titles in mkdocs.yml are sentence case.
    a. All the present gallery titles may be considered application names, and were capitalized as proper nouns. E.g. "(Apple) App Store" is an app store.
  2. Titles in page front matter // metadata are title case.
  3. All headers within a page must follow the same style (either title case or sentence case), but authors have the liberty to decide the style for their page (in case there may be a semantic benefit). Accordingly, I standardized letter case for headers in individual pages to whichever was more common in that page.

I'm not opposed to changing any of these rules, I just want them to apply consistently to the whole docs where applicable.

@arcanaxion
Copy link
Contributor Author

By the way, standardizing page title metadata to title case was just for convenience — I needed to make fewer changes for this.

I think matching the mkdocs.yml style of sentence case is probably better here too

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@FabienLelaquais FabienLelaquais FabienLelaquais requested changes

Requested changes must be addressed to merge this pull request.

Assignees
No one assigned
Labels
📄 Documentation Internal or public documentation 📈 Improvement Improvement of a feature. 🟧 Priority: High Stalls work on the project or its dependents
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@arcanaxion @FabienLelaquais