search

pymc-labs / pymc-marketing

Bayesian marketing toolbox in PyMC. Media Mix (MMM), customer lifetime value (CLV), buy-till-you-die (BTYD) models and more.
https://www.pymc-marketing.io/
Apache License 2.0
655 stars 180 forks source link

Speed up sphinx builds #650

Open wd60622 opened 4 months ago

wd60622 commented 4 months ago

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!

OriolAbril commented 3 months ago

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: ![imatge](https://github.com/pymc-labs/pymc-marketing/assets/23738400/97f32e8b-58dd-4771-95a1-f5e8bf2252a7) whole/regular build page (from website): ![imatge](https://github.com/pymc-labs/pymc-marketing/assets/23738400/e91bf3db-7bf9-4aff-921f-080d184072b8) 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: ![imatge](https://github.com/pymc-labs/pymc-marketing/assets/23738400/49bb909e-0567-473a-8e8a-7365ac565fd0) whole/regular builg page: ![imatge](https://github.com/pymc-labs/pymc-marketing/assets/23738400/999b777d-8cd9-4cd2-a3f7-a1107578b48f) 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: ![imatge](https://github.com/pymc-labs/pymc-marketing/assets/23738400/bfd969d6-f0a9-4b30-b4f6-b33d7d5aa2ed) 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?