Skip to content

Commit f9c0fa5

Browse files
authored
Add a command snippet to build only modified documentation (#10571)
Add a command snippet to build only modified documentation Clarified that the FILELIST feature isn't available on Windows, hint about WSL. Added examples for diff from HEAD and master.
1 parent 7d49576 commit f9c0fa5

File tree

1 file changed

+25
-0
lines changed

1 file changed

+25
-0
lines changed

contributing/documentation/building_the_manual.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,8 +162,33 @@ RAM for Sphinx alone.
162162
Specifying a list of files
163163
~~~~~~~~~~~~~~~~~~~~~~~~~~
164164

165+
.. warning::
166+
167+
This section will not work on Windows, since the repository is using
168+
a simplified ``make.bat`` script instead of the real GNU Make program.
169+
If you would like to get a Linux terminal on your system, consider using
170+
`Windows Subsystem for Linux (WSL) <https://learn.microsoft.com/en-us/windows/wsl/>`__.
171+
165172
You can specify a list of files to build, which can greatly speed up compilation:
166173

167174
.. code:: sh
168175
169176
make html FILELIST='classes/class_node.rst classes/class_resource.rst'
177+
178+
The list of files can also be provided by the ``git`` command.
179+
This way you can automatically get the names of all files that have changed since
180+
the last commit (``sed`` is used to put them on the same line).
181+
182+
.. code:: sh
183+
184+
make html FILELIST="$(git diff HEAD --name-only | sed -z 's/\n/ /g')"
185+
186+
You can replace ``HEAD`` with ``master`` to return all files changed from the
187+
``master`` branch:
188+
189+
.. code:: sh
190+
191+
make html FILELIST="$(git diff master --name-only | sed -z 's/\n/ /g')"
192+
193+
If any images were modified, the output will contain some warnings about them,
194+
but the build will proceed correctly.

0 commit comments

Comments
 (0)