Unable to get notebook sections to appear in build docs

[paw-lu]

Description of your problem

When trying to build the docs, all the notebook sections fail to make it into the built html.

(venv)% python -m pip install .

(venv)% python -m pip install -r requirements-dev.txt

(venv)% latesttag=$(git describe --tags `git rev-list --tags --max-count=1`)

(venv)% git checkout ${latesttag}

(venv)% git submodule update --remote

(venv)% cd docs/source

(venv)% make html

# Countless warnings about ipynb files not being included in the toctree
/Users/pawlu/Documents/personal/pymc3/docs/source/pymc-examples/examples/pymc3_howto/sampling_callback.ipynb: WARNING: document isn't included in any toctree

(venv)% open source/_build/html/index.html
...

As expected by the warnings, the sections derived from the example notebooks are blank. I tried to follow the steps outlied in build_and_deploy_docs.sh as close as possible, but am clearly still missing a step. The notebook files do exist in docs/source/pymc-examples, so I think they were cloned correctly.

1. Am I missing a step here in properly building the docs?
2. How can we make this process easier for first time contributers?

---

Thanks for the amazing library and documentation!

[OriolAbril]

It could be an issue with the html paths. From your screenshot it looks like you are at .../html/nb_tutorials/index.html. What do you have (if anything) in the following locations?

• .../html/notebooks/ or .../html/notebooks/nb_name.html
• .../html/pymc-examples/examples/ or .../html/pymc-examples/examples/getting_started.html

Relative paths are different locally than they are in docs.pymc.io so it could be that the notebooks are there and rendered correctly, but the sphinx extension that builds the index pages doesn't find them and is not generated and/or rendered correctly.

[paw-lu]

• html/notebooks does not exist on my system
• html/pymc-examples:

html/pymc-examples/examples
% ls
case_studies               generalized_linear_models  mixture_models  samplers           variational_inference
diagnostics_and_criticism  getting_started.html       ode_models      survival_analysis
gaussian_processes         getting_started.ipynb      pymc3_howto     time_series

html/pymc-examples/examples
❯ ls case_studies 
BEST.html                               log-gaussian-cox-process.html
BEST.ipynb                              log-gaussian-cox-process.ipynb
LKJ.html                                multilevel_modeling.html
LKJ.ipynb                               multilevel_modeling.ipynb
blackbox_external_likelihood.html       probabilistic_matrix_factorization.html
blackbox_external_likelihood.ipynb      probabilistic_matrix_factorization.ipynb
conditional-autoregressive-model.html   putting_workflow.html
conditional-autoregressive-model.ipynb  putting_workflow.ipynb
factor_analysis.html                    rugby_analytics.html
factor_analysis.ipynb                   rugby_analytics.ipynb
hierarchical_partial_pooling.html       stochastic_volatility.html
hierarchical_partial_pooling.ipynb      stochastic_volatility.ipynb

[paw-lu]

so it could be that the notebooks are there and rendered correctly, but the sphinx extension that builds the index pages doesn't find them and is not generated and/or rendered correctly.

Yeah I think I get what you're saying, though it seems from @MarcoGorelli's screenshos in #4348 (comment) that they were able to build locally and propertly see the tutorial notebooks.

[MarcoGorelli]

Hey @paw-lu

Can you try navigating to the _build/html directory, running python -m http.server and then opening localhost:8000 in the browser?

[paw-lu]

Thanks @MarcoGorelli! I wasn't aware this wasn't a static site. Thanks for the tip! This fixes any issues I had. The built documentation behaves as expected when running the python HTTP server.

---

Is there an interest in codifying this knowledge? I see #4483 was opened asking for a Python version of these scripts. There are a lot of scripts around root—like fast_build_docs.sh, build_and_deploy_docs.sh, buildosx—that could be consolidated into something more unified and discoverable.

There are two options off the top of my head:

• Makefile (example from Rich's repo)

  Pros: Universal, included in many systems, well-known
  Cons: Not Python, not a great command runner, Windows support?

• noxfile (example from pip's repo)

  Pros: Python, can install dependencies (like sphinx for building, serving docs), specifically constructed for these kinds of usecases
  Cons: Another tool to install, not as universal as make

Regardless, thanks for the help everyone!

[MarcoGorelli]

Is there an interest in codifying this knowledge?

I think so, yes - or at least, documenting it would be very useful!

[paw-lu]

Found that @Sayam753 had added some documentation in the wiki.

[Sayam753]

Awesome. Closing the issue now. Feel free to reopen if things break again.