Course build performance: take advantage of the Sphinx incremental build

[markkuriekkinen]

Sphinx by default builds only (RST) files that have been changed since the last build. Sphinx checks the timestamps (modification time) on the RST files and in the build cache directory _build/doctrees.

In a-plus-rst-tools, we use a command that breaks the incremental build: make touchrst html. touchrst is defined in the course Makefile and it touches all RST files in the course directory (touch sets the timestamp of the file to the current time). This is needed because Sphinx does not see changes in the course YAML files such as exercise config.yaml. If the RST file using some config.yaml is not touched, then the new build would exclude the changes in the config.yaml file and the new configuration would not be deployed at all.

Improve the course build time by taking advantage of the Sphinx incremental build. Do not touch all RST files at the start of the build. Gitmanager or the course Makefile could touch only those RST files that are needed to include the changes in the YAML files. New updates to YAML files should be somehow detected so that the corresponding RST files may be included in the build.

• YAML file changes could be detected from the new git commits that have been pulled. Inspect the changes in the git commits to detect the updated files.
• Alternatively, YAML file changes could be detected simply from the file timestamps. Which way performs better?
• RST files could be touched to include them in the new incremental Sphinx build.
• Instead of touching, the RST files to be built could also be supplied to the sphinx-build command as parameters. Sphinx-build is called in the course Makefile.

https://www.sphinx-doc.org/en/master/man/sphinx-build.html

By default, everything that is outdated is built. Output only for selected files can be built by specifying individual filenames.

Related to apluslms/a-plus-rst-tools#89

[lainets]

apluslms/a-plus-rst-tools#156 adds this support. However, it should be noted that the build output directory needs to be specified in the exclude_patterns field of the meta file, otherwise the git clean command will remove the files and the build will be done from scratch.