[PATCH 1/1] doc: describe our documentation style

[Simon Glass]

On Fri, 7 Apr 2023 at 21:28, Heinrich Schuchardt
<heinrich.schuchardt at canonical.com> wrote:
>
> Provide a reference document for the U-Boot documentation style.
>
> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at 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 at chromium.org>