Skip to content

Add ReStructuredText formatter to CI #68430

Open
@kartben

Description

@kartben

Is your enhancement proposal related to a problem? Please describe.

Formatting of .rst documentation is very inconsistent, mainly due to the lack of CI-enforced formatting checks. As always with problems like this, it is not the end of the world per se but can lead to diffs that are harder to digest than necessary, and overall doc pages that look 'all over the place' when opened in an editor.

Describe the solution you'd like

A .rst linter / code formatting tool hooked up in CI / check compliance script that ensures documentation files are properly formatted.

Describe alternatives you've considered

An alternative, that maybe should be its own RFC, would be to approach text documentation differently: we could simply state that it's "one sentence, one line" (however long it needs to be).

This has IMO the significant benefit of making changes to a sentence easier to spot, and not have them "bleed" in the diff, for they would literally be one line. It also makes it easier for folks to not overlook the need to make text breathe by adding actual blank lines. Right now, in my experience, a lot of people add simple line returns in their source doc thinking they will "show" in the rendered docs, except that they do nothing...
A drawback is that enforcing this guideline in CI might actually be harder than the 100-char wrapping one..?

IIUC from previous comments on PR, this approach is used by Nordic? @gmarull

Additional context

In any case, adding such a CI check would require a tree-wide reformatting of the existing .rst files, with thorough QA that rendered output hasn't been altered.

Metadata

Metadata

Assignees

No one assigned

    Projects

    Status

    🆕 New

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions