New scripts/requirements-lax.txt with '>=' instead of '=='

algos/demux/demux.rst

@@ -59,7 +59,7 @@ hexadecimal or integer values. SOF topology m4 macros have helpers to
 The following example from pipe-volume-demux-playback.m4 shows how to define
 2 routing matrices and a demux component:
 
-.. code-block::
+.. code-block:: text
 
 		# pipeline_id, channels, matrix_rows
 		define(matrix1, `ROUTE_MATRIX(PIPELINE_ID, 2,
@@ -118,7 +118,7 @@ python tool:
 
 It produces the following output:
 
-.. code-block::
+.. code-block:: text
 
 		sof m4 and ALSA conf format:
 		`       bytes "0x53,0x4f,0x46,0x00,0x12,0x00,0x00,0x00,0x3c,'

contribute/process/docbuild.rst

@@ -147,6 +147,16 @@ tools:
    cd ~/thesofproject/sof-docs
    pip3 install --user -r scripts/requirements.txt
 
+Note :git-sof-docs-master:`scripts/requirements.txt` hardcodes versions
+using ``==``, which may not be compatible with your other projects. In
+that case you can either setup a Python ``virtualenv`` or try the
+unsupported :git-sof-docs-master:`scripts/requirements-lax.txt` (more
+details inside this file):
+
+.. code-block:: bash
+
+   PIP_IGNORE_INSTALLED=0 pip3 install --user -r scripts/requirements-lax.txt
+
 For Windows, install the needed tools manually:
 
 * Python (3.7+) from https://www.python.org/downloads/
@@ -171,7 +181,8 @@ For Windows, install the needed tools manually:
    Make sure that installed executable files are in your path. If not,
    manually add the paths to the PATH variable.
 
-For Linux and Windows, install the remaining python-based tools:
+For Windows, install the remaining python-based tools as already
+described for Linux above:
 
 .. code-block:: bash
 

scripts/requirements-lax.txt

@@ -0,0 +1,46 @@
+# Do not use this file for any intensive/"serious" documentation work.
+
+# The purpose of this "laxer" file is to lower the barrier for drive-by
+# contributors and make it easier for anyone to verify a typo fix
+# locally.
+
+# On Debian/Ubuntu/etc. don't forget PIP_IGNORE_INSTALLED=0 (double
+# negation):
+#  PIP_IGNORE_INSTALLED=0 pip3 install --user -r scripts/requirements-lax.txt
+# See https://github.com/pypa/pip/issues/4222
+
+breathe>=4.7.3
+sphinx>=1.6.7
+docutils>=0.14
+sphinx_rtd_theme>=0.2.4
+sphinxcontrib-plantuml
+
+
+# Differences between these "lax" version requirements and the official
+# ones in requirements.txt:
+
+## Pros
+
+#  - They use '>=' instead of '==' hardcoding so:
+#      - you don't need a virtualenv per project,
+#      - you can spend less time downloading and more time fixing the doc.
+#  - The build was successful the last time someone updated this file.
+#  - These versions produce something usable and mostly complete.
+
+## Cons
+
+#  - They're not official, not regulary tested and "best effort",
+#    community-maintained.
+#  - They may produce warnings (but nothing that stops the build).
+#  - Output may be ugly and/or incomplete.
+#  - Upgrading only some of them outside this file may result in sphinx
+#    modules incompatible with each other.
+
+## Maintenance
+
+#  - Bump up only when really needed. Prefer (reasonable) backward
+#    compatibility if possible,
+#  - When bumping up, upgrade to the lowest possible version required.
+#  - Downgrade if successfully tested.
+#  - Test with plantum set to "none" in conf.py. We don't want small
+#    typo fixes to depend on UML diagrams.

scripts/requirements.txt

@@ -1,3 +1,5 @@
+# This file hardcodes validated versions with '==',
+# see requirements-lax.txt for an alternative.
 breathe==4.14.1
 sphinx==2.4.4
 docutils==0.16