Project

General

Profile

Feature #3030

RST style guidelines

Added by Eric Irrgang 3 months ago.

Status:
New
Priority:
Normal
Assignee:
-
Category:
documentation
Target version:
-
Difficulty:
uncategorized
Close

Description

This is a request for an additional style guideline for the project documentation itself.

I can create an initial candidate with preliminary responses to the following points and any initial brain-storming offered.

The ReStructuredText have several patterns that may be extraneous artifacts or that may have a purpose, but this is not clear. See, for instance, the tendency to use explicit labels for documents in the dev guide instead of the default document name derived from the file, or the inconsistent use of overline for document headings.

Several conventions that are more or less arbitrary but which need to be consistent ought to be prescribed somewhere, such as document section syntax. See, for instance, https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections and http://docutils.sourceforge.net/docs/user/rst/quickref.html#section-structure

Also available in: Atom PDF