some more updates to api section

Author: OriolAbril

docs/source/Makefile renamed to Makefile

@@ -5,7 +5,8 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+SOURCEDIR     = docs/source
+BUILDDIR      = docs/_build
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -51,9 +52,11 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(SOURCEDIR)/api/**/generated
+	rm -rf docs/jupyter_execute
 
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) $(SOURCEDIR) $(BUILDDIR) -b html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 

docs/source/api.rst

@@ -15,11 +15,34 @@ API Reference
    api/smc
    api/step_methods
    api/inference
-   api/plots
 
-Indices and tables
-===================
+--------------
+API extensions
+--------------
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+Plots, stats and diagnostics
+----------------------------
+Plots, stats and diagnostics are delegated to the
+:doc:`ArviZ <arviz:index>`.
+library, a general purpose library for
+"exploratory analysis of Bayesian models".
+
+* Functions from the `arviz.plots` module are available through ``pymc.<function>`` or ``pymc.plots.<function>``,
+but for their API documentation please refer to the :ref:`ArviZ documentation <arviz:plot_api>`.
+
+* Functions from the `arviz.stats` module are available through ``pymc.<function>`` or ``pymc.stats.<function>``,
+but for their API documentation please refer to the :ref:`ArviZ documentation <arviz:stats_api>`.
+
+ArviZ is a dependency of PyMC and so, in addition to the locations described above,
+importing arviz and using ``arviz.<function>`` will also work without any extra installation.
+
+Generalized Linear Models (GLMs)
+--------------------------------
+
+Generalized Linear Models are delegated to the
+`Bambi <https://bambinos.github.io/bambi>`_.
+library, a high-level Bayesian model-building
+interface built on top of the PyMC.
+
+Bambi is not a dependency of PyMC and should be installed in addition to PyMC
+to use it to generate PyMC models via formula syntax.

docs/source/api/distributions/simulator.rst

@@ -2,7 +2,7 @@
 Simulator
 **********
 
-.. currentmodule:: pymc.distributions.simulator
+.. currentmodule:: pymc
 .. autosummary::
    :toctree: generated
 

docs/source/api/distributions/timeseries.rst

@@ -2,7 +2,7 @@
 Timeseries
 **********
 
-.. currentmodule:: pymc.distributions.timeseries
+.. currentmodule:: pymc
 .. autosummary::
    :toctree: generated
 

docs/source/api/distributions/utilities.rst

@@ -4,10 +4,10 @@ Distribution utilities
 
 .. currentmodule:: pymc
 .. autosummary::
-   :toctree: generated
+   :toctree: generated/
 
-  Distribution
-  Discrete
-  Continuous
-  NoDistribution
-  DensityDist
+    Distribution
+    Discrete
+    Continuous
+    NoDistribution
+    DensityDist

docs/source/api/glm.rst

@@ -118,7 +118,7 @@
 # myst and panels config
 jupyter_execute_notebooks = "off"
 myst_enable_extensions = ["colon_fence", "deflist", "dollarmath", "amsmath", "substitution"]
-myst_heading_anchors = 0
+myst_heading_anchors = None
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -191,7 +191,6 @@
     "navbar_end": ["search-field.html", "navbar-icon-links.html"],
     "search_bar_text": "Search...",
     "use_edit_page_button": False,  # TODO: see how to skip of fix for generated pages
-    "externalrefs": True,
     "google_analytics_id": "UA-176578023-1",
 }
 html_context = {

docs/source/api/plots.rst

@@ -2,13 +2,21 @@
 
 To build the docs, run these commands at pymc repository root:
 
-TODO: fix makefile
-
 ```bash
 $ pip install -r requirements-dev.txt  # Make sure the dev requirements are installed
-$ cd docs/source
-$ make html  # Build docs
-$ python -m http.server --directory ../_build/html  # Render docs
+$ make clean  # clean built docs from previous runs and intermediate outputs
+$ make html   # Build docs
+$ python -m http.server --directory ../_build/  # Render docs
 ```
 
 Check the printed url where docs are being served and open it.
+
+The `make clean` step is not always necessary, if you are working on a specific page
+for example, you can rebuild the docs without the clean step and everything should
+work fine. If you are restructuring the content or editing toctrees, then you'll need
+to execute `make clean`.
+
+A good approach is to skip the `make clean`, which makes
+the `make html` blazing fast and see how everything looks.
+If something looks strange, run `make clean` and `make html` one after the other
+to see if it fixes the issue before checking anything else.