carla/Docs/cont_doc_standard.md

Documentation Standard

This document will serve as a guide and example of some rules that need to be followed in order to contribute to the documentation.

• Docs structure
• Rules
• Exceptions

---

Docs structure

We use a mix of markdown and HTML tags to customize the documentation along with an extra.css file. To update Python API docs, instead of directly modifying the Markdown you need to edit the corresponding YAML files inside carla/PythonAPI/docs/ and run doc_gen.py or make PythonAPI.docs.

This will re-generate the respective Markdown files inside carla/Docs/, which can then be fed into mkdocs.

---

Rules

• Leave always an empty line between sections and at the end of the document.
• Writting should not exceed 100 columns, except for HTML related content, markdown tables, code snipets and referenced links.
• If an inline link exceeds the limit, use referenced [name][reference_link] markdown notation [reference_link]: https:// rather than [name](https://).
• Use <br> to make inline jumps rather than leaving two spaces at the end of a line.
• Use <h1>Title</h1> at the beggining of a new page in order to make a Title or <hx>Heading<hx> to make a heading that won't show on the navigation bar.
• Use ------ underlining a Heading or # hierarchy to make headings and show them in the navigation bar.

---

Exceptions

• Documentation generated via Python scripts like PythonAPI reference

Handy markdown cheatsheet.