diff --git a/contributing/documentation/building_the_manual.rst b/contributing/documentation/building_the_manual.rst index 60a338e12..eb732febc 100644 --- a/contributing/documentation/building_the_manual.rst +++ b/contributing/documentation/building_the_manual.rst @@ -162,8 +162,33 @@ RAM for Sphinx alone. Specifying a list of files ~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. warning:: + + This section will not work on Windows, since the repository is using + a simplified ``make.bat`` script instead of the real GNU Make program. + If you would like to get a Linux terminal on your system, consider using + `Windows Subsystem for Linux (WSL) `__. + You can specify a list of files to build, which can greatly speed up compilation: .. code:: sh make html FILELIST='classes/class_node.rst classes/class_resource.rst' + +The list of files can also be provided by the ``git`` command. +This way you can automatically get the names of all files that have changed since +the last commit (``sed`` is used to put them on the same line). + +.. code:: sh + + make html FILELIST="$(git diff HEAD --name-only | sed -z 's/\n/ /g')" + +You can replace ``HEAD`` with ``master`` to return all files changed from the +``master`` branch: + +.. code:: sh + + make html FILELIST="$(git diff master --name-only | sed -z 's/\n/ /g')" + +If any images were modified, the output will contain some warnings about them, +but the build will proceed correctly.