Create make docs-quick that reduces docs build time

[purva-thakre]

mitiq/Makefile

Lines 34 to 41 in b7b6e1e

	.PHONY: docs
	docs:
	make -C docs html
	.PHONY: docs-clean
	docs-clean:
	make -C docs clean
	make -C docs html

The above commands let us build the documentation locally. But as the docs build takes forever, working on documentation layout-related issues becomes unmanageable. For example, #2331 and #2330 are relatively minor issues that could be fixed quickly if one could make minor changes and test the build locally for the layout (repetitively).

I think it would be better to conditionally use the exclude_patterns directive to create a make docs-quick that lets us skip the portions of the documentation that take a loooong time. This is useful if we are testing for the docs layout and not the actual material in the documentation.

https://stackoverflow.com/a/34075856

mitiq/docs/source/conf.py

Lines 87 to 90 in b7b6e1e

	# List of patterns, relative to source directory, that match files and
	# directories to ignore when looking for source files.
	# This pattern also affects html_static_path and html_extra_path.
	exclude_patterns = []

[purva-thakre]

sphinx-needs could be used to check which portions of the docs build take the longest and are to be included in the exclude_patterns directive.

[purva-thakre]

Apparently, there is an option to not execute the notebooks according to Alessandro's comment.

https://discord.com/channels/764231928676089909/773957956659052605/1238537333964411001

This involves changing cache to off below:

mitiq/docs/source/conf.py

Line 128 in 9a90339

nb_execution_mode = "cache"

https://myst-nb.readthedocs.io/en/v0.12.2/use/execute.html#triggering-notebook-execution

Closing this issue.

[cosenal]

I think cache is the right configuration here and one shouldn't need to switch it off. We can't trivially use caching in CI¹, but for local development it should work well. If for whatever reason, that's not the case for you, then we should investigate those scenarios.

@jordandsullivan you mentioned you find yourself often in the need to run make docs-clean, but at the same time not you don't want to run the notebooks. Can you elaborate on these scenarios?

Footnotes

1. a solid attempt was made in https://github.com/unitaryfund/mitiq/pull/2279 – if I say so myself 🙄 ↩

[purva-thakre]

@cosenal If we make changes to the template, it's better to use make docs-clean because you can't see the changes sometimes.

[cosenal]

@purva-thakre can you elaborate even more, ideally with a concrete example? I have been making changes to the template, and make docs has been working just fine 🤷🏻‍♂️

[purva-thakre]

@cosenal Sure! I'll dig through my older PRs and add that example to this discussion later.

Working on one such PR made me aware that make docs-clean has to be used if we are making changes to the layout, templates, etc. The changes would not show up in a local build if I used make docs. The older files had to be removed first.

[cosenal]

👍 Maybe we are talking about different templates that we are changing. Looking forward to those examples.