From 624faeecec5b0df74791d7eac3f9984673f5b33b Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Fri, 7 Apr 2023 11:28:00 +0200 Subject: [PATCH] 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 --- 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..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 -- 2.39.5