Hi All,

I have recently pushed a patch based on the proposal.

Please feel free to review and comment.

https://review.trustedfirmware.org/c/TF-M/trusted-firmware-m/+/6622

Minos

From: Gyorgy Szing <Gyorgy.Szing@arm.com>
Sent: 01 July 2020 12:02
To: Minos Galanakis <Minos.Galanakis@arm.com>; tf-m@lists.trustedfirmware.org <tf-m@lists.trustedfirmware.org>
Cc: nd <nd@arm.com>; nd <nd@arm.com>
Subject: RE: [RFC] TF-M Documentation Contribution Format
 

Hi,

 

I think this effort should be done together with other tf.org projects using the same technology (Sphinx). Can you pls sync up with the TF-A team?

 

Related to the details:

 

[1] https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html

/George

 

From: TF-M <tf-m-bounces@lists.trustedfirmware.org> On Behalf Of Minos Galanakis via TF-M
Sent: 30 June 2020 16:23
To: tf-m@lists.trustedfirmware.org
Cc: nd <nd@arm.com>
Subject: [TF-M] [RFC] TF-M Documentation Contribution Format

 

Hi,

 

As the project matures, and the community grows, I would like to revive an old discussion and suggest that we set

some guidelines for contributing to the project's documentation.

 

I would like to propose that we establish a minimal sub-set of rules, based on the

official Python guidelines which is the most widely used notation. This offers compatibility with

existing tools for proofing and producing said documentation.

 

The following rules should be considered:

   

  1.     H1 document title headers should be expressed by # with over-line  (rows on top and bottom) of the text
  2.     Only ONE H1 header should allowed per document, ideally placed on top of the page.
  3.     H2 headers should be expressed by * with over-line
  4.     H2 header's text should be UNIQUE in per document basis
  5.     H3 headers should be expressed by a row of '='
  6.     H4 headers should be expressed by a row of '-'
  7.     H3 and H4 headers have no limitation about naming. They can have similar names on the same document, as long as they have different parents.
  8.     H5 headers should be expressed by a row of '^'
  9.     H5 headers will be rendered in document body but not in menus on the navigation bar.
  10.     Do not use more than 5 level of heading
  11.     When writing guide, which are expected to be able to be readable by command line tools, it would be best practice to add long complicated  tables, and UML diagrams in the bottom of the page and using internal references(auto-label). Please refer to the `tfm_sw_requirement.rst` as an example
  12.     No special formatting should be allowed in Headers ( code, underline, strike-through etc )
  13.     Long URLs and external references should be placed at the bottom of the page and referenced in the body of the document
  14.     New introduced terms and abbreviations should be added to Glossary and directly linked by the `:term:` notation across all documents using it.

 

When something new, which is not covered is required, the rule should be first to follow the any reference to of an existing document, and the Python Documentation rules otherwise.

 

Please let me know if you have any questions/objection or proposals or new rules you would like to consider. Any feedback is more than welcome.

 

Minos