Ferrite-FEM / Ferrite-FEM/Ferrite.jl

Docs: Consistent formatting for capitalization of headers

Open
#1,156 0 comments 2 reactions 0 assignees View on GitHub
docs
Dominant language
Julia
Stars
453
Forks
115
Avg merge
1d 17h
Merged PRs (30d)
11

Description

This is a very trivial issue and arose as I was working on https://github.com/Ferrite-FEM/Ferrite.jl/pull/1138. There is not a consistent formatting for the capitalization of headers in the documentation. For example, in the [Stokes Flow Tutorial](https://ferrite-fem.github.io/Ferrite.jl/stable/tutorials/stokes-flow/), headers are written using sentence case (i.e., only the first word and any proper nouns are capitalized) as in `## Introduction and problem formulation` while in other tutorials such as [Transient Heat Equation Tutorial](https://ferrite-fem.github.io/Ferrite.jl/stable/tutorials/transient_heat_equation/) headers are written using title case (i.e., capitalize nouns, pronouns, verbs, adjectives, and adverbs, but do not capitalize short conjunctions, prepositions, or articles unless they are the first or last word) as in `## Commented Program`.

It seems like the sentence case is the more widely used capitalization style used in the documentation, so I could easily make a PR correcting the places in the docs that don't adhere to this, but I wanted to open the issue first in case there is a preference by the lead maintainers for a certain style. **Update:** https://github.com/Ferrite-FEM/Ferrite.jl/pull/1175 resolves this!

- [x] Manually update docs with sentence case. Resolved https://github.com/Ferrite-FEM/Ferrite.jl/pull/1175.

It may also be beneficial to update the CI (e.g., maybe runic or perhaps somewhere else in the github workflows) to enforce whatever the desired style is. I could also make this addition, by I would appreciate it if someone could point to which file they think it would be appropriate to make this type of style enforcing addition to. This capitalization style should naturally only affect code changes in `docs/` (e.g., should someone wish to add a new topic guide, the topic name `My Topic` would error but the topic name `My topic` would pass CI). **Update:** This is not yet addressed, and could be a `good-first-issue`. I can look into this later if no one else claims it, but there are other issues/PRs i need to address first.

- [ ] Update CI to enforce desired style. Still an open issue.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.