From: Heinrich Schuchardt Date: Fri, 7 Apr 2023 09:28:00 +0000 (+0200) Subject: doc: describe our documentation style X-Git-Url: http://git.dujemihanovic.xyz/?a=commitdiff_plain;h=624faeecec5b0df74791d7eac3f9984673f5b33b;p=u-boot.git doc: describe our documentation style Provide a reference document for the U-Boot documentation style. Signed-off-by: Heinrich Schuchardt Reviewed-by: Tom Rini Reviewed-by: Simon Glass --- diff --git a/doc/develop/docstyle.rst b/doc/develop/docstyle.rst new file mode 100644 index 0000000000..f9ba83a559 --- /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 `_ 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 `_. +* For documentation within code we follow the Linux kernel guide + `Writing kernel-doc comments `_. +* 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