diff options
| author | Heinrich Schuchardt | 2023-04-07 11:28:00 +0200 |
|---|---|---|
| committer | Heinrich Schuchardt | 2023-04-08 07:44:33 +0200 |
| commit | 624faeecec5b0df74791d7eac3f9984673f5b33b (patch) | |
| tree | b914e04a4141bb354107d2c70954591cf15a293b | |
| parent | 19d0c64f89ee5a0d5d3077e5d7ec7dafd74a0d45 (diff) | |
doc: describe our documentation style
Provide a reference document for the U-Boot documentation style.
Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
Reviewed-by: Tom Rini <trini@konsulko.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
| -rw-r--r-- | doc/develop/docstyle.rst | 29 | ||||
| -rw-r--r-- | doc/develop/index.rst | 1 |
2 files changed, 30 insertions, 0 deletions
diff --git a/doc/develop/docstyle.rst b/doc/develop/docstyle.rst new file mode 100644 index 00000000000..f9ba83a559c --- /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 a52ad630d0d..ddbf8dad4a1 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -11,6 +11,7 @@ General codingstyle designprinciples + docstyle patman process release_cycle |