On Fri, 7 Apr 2023 at 21:28, Heinrich Schuchardt heinrich.schuchardt@canonical.com wrote:
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
-- 2.39.2
Reviewed-by: Simon Glass sjg@chromium.org