Anastasia Klimchuk has submitted this change. ( https://review.coreboot.org/c/flashrom/+/74225 )
Change subject: doc: Add doc how to add docs ......................................................................
doc: Add doc how to add docs
Change-Id: I356a286ad2f3334392efadda366b0ca0f8042752 Signed-off-by: Anastasia Klimchuk aklm@chromium.org Reviewed-on: https://review.coreboot.org/c/flashrom/+/74225 Tested-by: build bot (Jenkins) no-reply@coreboot.org Reviewed-by: Alexander Goncharov chat@joursoir.net Reviewed-by: Angel Pons th3fanbus@gmail.com --- A doc/how_to_add_docs.rst M doc/index.rst 2 files changed, 50 insertions(+), 0 deletions(-)
Approvals: build bot (Jenkins): Verified Angel Pons: Looks good to me, approved Alexander Goncharov: Looks good to me, but someone else must approve
diff --git a/doc/how_to_add_docs.rst b/doc/how_to_add_docs.rst new file mode 100644 index 0000000..0b32acb --- /dev/null +++ b/doc/how_to_add_docs.rst @@ -0,0 +1,35 @@ +How to add or update docs +========================= + +To add or update a documentation page, you need to create or modify +an ``.rst`` file in the ``/doc`` directory and send a patch for +review. + +People who are registered in MAINTAINERS file for doc/ directory will +be automatically added to the patch as reviewers. However, you are +very welcome to add more reviewers who know the subject. In fact, it +is always a good idea to add someone who has knowledge of the specific +area you are documenting. + +We are using Sphinx doc engine for documentation (see +https://www.sphinx-doc.org/) and reStructured Text format for content. +reStructuredText Primer page has more details +https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rest... + +Brand new page needs to be added to the appropriate ``index.rst`` file +under ``/doc`` directory (that could be a root index file or nested one). + +To test your changes, build flashrom with documentation and open +generated ``.html`` file in the browser. Generated ``.html`` files are +in meson ``builddir/doc/html`` directory. + +Misc questions +-------------- + +* We use CC-BY-4.0 license for documentation. +* Writing style can be formal or informal, it's mostly up to you, the + important thing is to make the text clear, readable and unambiguous. You + can insert images if this really helps the readers to understand the + instructions. +* Documentation should be relevant to either flashrom usage or flashrom + development diff --git a/doc/index.rst b/doc/index.rst index 326f684..e6dcc4d 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,5 +9,6 @@ dev_guide/index classic_cli_manpage contact + how_to_add_docs
.. include:: ../README.rst