Provide a reference document for the U-Boot documentation style.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com --- doc/develop/docstyle.rst | 29 +++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 30 insertions(+) create mode 100644 doc/develop/docstyle.rst
diff --git a/doc/develop/docstyle.rst b/doc/develop/docstyle.rst new file mode 100644 index 0000000000..e64b669b8a --- /dev/null +++ b/doc/develop/docstyle.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Documentation Style +=================== + +Documentation is crucial for the U-Boot project. It has to encompass the needs +of different reader groups from first time users to developers and maintainers. +This requires different types of documentation like tutorials, how-to-guides, +explanatory texts, and reference. + +We want to be able to generate documentation in different target formats. We +therefore use `Sphinx https://www.sphinx-doc.org`_ for the generation of +documents from reStructured text. + +We apply the following rules: + +* Documentation files are located in *doc/* or its sub-directories. +* Each documentation file is added to an index page to allow navigation + to the document. +* For documentation we use reStructured text conforming to the requirements + of `Sphinx https://www.sphinx-doc.org`_. +* For documentation within code we follow the Linux kernel guide + `Writing kernel-doc comments https://docs.kernel.org/doc-guide/kernel-doc.html`_. +* We try to stick to 80 columns per line in documents. +* For tables we prefer simple tables over grid tables. We avoid list tables + as they make the reStructured text documents hard to read. +* Before submitting documentation patches we build the HTML documentation and + fix all warnings. The build process is described in + :doc:`/build/documentation`. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index a52ad630d0..ddbf8dad4a 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -11,6 +11,7 @@ General
codingstyle designprinciples + docstyle patman process release_cycle