1 files changed, 62 insertions, 28 deletions

diff --git a/documentation/README b/documentation/README
index 8035418cac..56eac7ca19 100644
--- a/documentation/README
+++ b/documentation/README
@@ -108,32 +108,9 @@ generated with DocBook.
 How to build the Yocto Project documentation
 ============================================
 
-Sphinx is written in Python. While it might work with Python2, for
-obvious reasons, we will only support building the Yocto Project
-documentation with Python3.
-
-Sphinx might be available in your Linux distro packages repositories,
-however it is not recommended to use distro packages, as they might be
-old versions, especially if you are using an LTS version of your
-distro. The recommended method to install the latest versions of Sphinx
-and of its required dependencies is to use the Python Package Index (pip).
-
-To install all required packages run:
-
- $ pip3 install sphinx sphinx_rtd_theme pyyaml
-
-To make sure you always have the latest versions of such packages, you
-should regularly run the same command with an added "--upgrade" option:
-
- $ pip3 install --upgrade sphinx sphinx_rtd_theme pyyaml
-
-Also install the "inkscape" package from your distribution.
-Inkscape is need to convert SVG graphics to PNG (for EPUB
-export) and to PDF (for PDF export).
-
-Additionally install "fncychap.sty" TeX font if you want to build PDFs. Debian
-and Ubuntu have it in "texlive-latex-extra" package while RedHat distributions
-and OpenSUSE have it in "texlive-fncychap" package for example.
+To build the documentation, you need Sphinx and a few other packages,
+which depend on your host GNU/Linux distribution. Such packages are listed on
+https://docs.yoctoproject.org/dev/ref-manual/system-requirements.html#required-packages-for-the-build-host
 
 To build the documentation locally, run:
 
@@ -165,6 +142,36 @@ To run Vale:
 
  $ make stylecheck
 
+Style checking the whole documentation might take some time and generate a
+lot of warnings/errors, thus one can run Vale on a subset of files or
+directories:
+
+  $ make stylecheck VALEDOCS=<file>
+  $ make stylecheck VALEDOCS="<file1> <file2>"
+  $ make stylecheck VALEDOCS=<dir>
+
+Lint checking the Yocto Project documentation
+=============================================
+
+To fix errors which are not reported by Sphinx itself,
+the project uses sphinx-lint (https://github.com/sphinx-contrib/sphinx-lint).
+
+To install sphinx-lint:
+
+ $ pip install sphinx-lint
+
+To run sphinx-lint:
+
+ $ make sphinx-lint
+
+Lint checking the whole documentation might take some time and generate a
+lot of warnings/errors, thus one can run sphinx-lint on a subset of files
+or directories:
+
+  $ make sphinx-lint SPHINXLINTDOCS=<file>
+  $ make sphinx-lint SPHINXLINTDOCS="<file1> <file2>"
+  $ make sphinx-lint SPHINXLINTDOCS=<dir>
+
 Sphinx theme and CSS customization
 ==================================
 
@@ -307,6 +314,16 @@ See https://stackoverflow.com/questions/27420317/restructured-text-rst-http-link
 Anchor (<#link>) links are forbidden as they are not checked by Sphinx during
 the build and may be broken without knowing about it.
 
+It is also possible to refer to another document within yocto-docs with the
+:doc: directive (c.f.
+https://www.sphinx-doc.org/en/master/usage/referencing.html#role-doc), e.g.:
+
+  For more information, read :doc:`/bsp-guide/index`.
+
+Note that only "absolute" paths (starting with a '/') are allowed. The root
+directory of that path is documentation/, that is, :doc:`/bsp-guide/index`
+points at documentation/bsp-guide/index.rst.
+
 References
 ==========
 
@@ -399,5 +416,22 @@ both the Yocto Project and BitBake manuals:
 Submitting documentation changes
 ================================
 
-Please see the top level README file in this repository for details of where
-to send patches.
+Please refer to our contributor guide here: https://docs.yoctoproject.org/contributor-guide/
+for full details on how to submit changes.
+
+As a quick guide, patches should be sent to docs@lists.yoctoproject.org
+The git command to do that would be:
+
+     git send-email -M -1 --to docs@lists.yoctoproject.org
+
+The 'To' header can be set as default for this repository:
+
+     git config sendemail.to docs@lists.yoctoproject.org
+
+Now you can just do 'git send-email origin/master..' to send all local patches.
+
+Read the other sections in this document and documentation/standards.md for
+rules to follow when contributing to the documentation.
+
+Git repository: https://git.yoctoproject.org/yocto-docs
+Mailing list: docs@lists.yoctoproject.org