Anastasia Klimchuk submitted this change.

View Change


Approvals: build bot (Jenkins): Verified Angel Pons: Looks good to me, approved Alexander Goncharov: Looks good to me, but someone else must approve
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(-)

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#restructuredtext-primer
+
+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

To view, visit change 74225. To unsubscribe, or for help writing mail filters, visit settings.

Gerrit-Project: flashrom
Gerrit-Branch: master
Gerrit-Change-Id: I356a286ad2f3334392efadda366b0ca0f8042752
Gerrit-Change-Number: 74225
Gerrit-PatchSet: 7
Gerrit-Owner: Anastasia Klimchuk <aklm@chromium.org>
Gerrit-Reviewer: Alexander Goncharov <chat@joursoir.net>
Gerrit-Reviewer: Anastasia Klimchuk <aklm@chromium.org>
Gerrit-Reviewer: Angel Pons <th3fanbus@gmail.com>
Gerrit-Reviewer: Edward O'Callaghan <quasisec@chromium.org>
Gerrit-Reviewer: Thomas Heijligen <src@posteo.de>
Gerrit-Reviewer: build bot (Jenkins) <no-reply@coreboot.org>
Gerrit-MessageType: merged