pymc-marketing
pymc-marketing copied to clipboard
pymc-labs
Speed up sphinx builds
It would be awfully convenient to be able to build a single notebook, only the notebooks, or specific module docstrings.
The make html command is very helpful. However, the build takes some time
https://github.com/pymc-labs/pymc-marketing/blob/91564cfbcce3d341d3d9bdab91a5b25766764b5a/Makefile#L20-L22
For notebooks, the sphinx rendering is a bit different than the jupyter notebook which can cause render issues not seen.
Not sure if this is possible though!
It is possible to some extent. It should work to quickly check some rendering issues, but many cross-references might break, as sphinx needs to generate the documentation as a whole for all cross-references to be resolvable.
Full background and examples (foldable)
For example, if I use sphinx-build docs/source docs/build -b html -D include_patterns=index.md,notebooks/mmm/mmm_example.ipynb I get a 2 page build that takes a couple seconds and renders the notebook page:
"fast" build page:
whole/regular build page (from website):
Save the sidebar and navbar that are mostly missing (given there are now no other pages in the website so they aren't being populated) everything looks good. If we take a bit more in depth look however, to the "tip" box:
"fast" build page:
whole/regular builg page:
The other notebooks are not part of the "fast" build, so the cross-references pointing to them can't be resolved and therefore don't result in any link, but that doesn't mean their syntax is wrong, they are in fact valid cross-references.
If we modify a bit the build command to include these referenced pages sphinx-build docs/source docs/build -b html -D include_patterns=index.md,notebooks/mmm/mmm_example.ipynb,notebooks/mmm/mmm_lift_test.ipynb,notebooks/mmm/mmm_budget_allocation_example.ipynb now we get:
the nabvar and sidebar are still broken as there is no proper navigation path with only the files included, but the cross-references are now resolved successfully.
What do you think would be the best way to go about that? Documenting how to use include_patterns and exclude_patterns with sphinx-build directive? Or are there common subsets which would make it preferrable to add the commands to the makefile with make mmm to generate the docs of mmm related files or make no-notebooks to exclude notebooks?
