Hi
With our documentation growing, and more people contributing to it, it is quite essential to start a discussion on some basic commonly accepted rules about the format of choice.
Restructured text allows you to achieve similar looking results using multiple approaches, but this makes it harder for tools like Sphinx to render properly, since the rendering template can be applied on per project basis, not on a per file basis. I took the liberty of investigating the existing documentation, and mostly looking for top level headers which can be done by using either
####################
This is a top-level header
####################
# Reference docs: # design_documents/tfm_its_service.rst # design_documents/secure_boot_hw_key_integration.rst
# Reference docs: # user_guides/tfm_secure_boot.rst # user_guides/tfm_user_guide.rst
or
==================== This is a top level header ====================
# Reference docs: # design_documents/tfm_its_service.rst # design_documents/secure_boot_hw_key_integration.rst
Since we are looking for the path of least resistance, I would like to propose that we follow the format the majority of document uses.This is the format used in `user_guides/tfm_user_guide.rsthttps://git.trustedfirmware.org/trusted-firmware-m.git/plain/docs/user_guides/tfm_user_guide.rst` .
When writing a document and coming across a requirement that has not been defined yet, we should be aiming for compliance with official Python guidelineshttps://devguide.python.org/documenting/#style-guide which is the most commonly used notation.
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, if 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 go deeper 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). See the current version of the `/user_guides/tfm_sw_requirement.rsthttps://git.trustedfirmware.org/trusted-firmware-m.git/plain/docs/user_guides/tfm_sw_requirement.rst` and the proposed patchhttps://review.trustedfirmware.org/c/trusted-firmware-m/+/2456
Please let me know if you have any questions/objection or proposals or new rules you would like to be considered.
Thanks, Minos