Sphinx error building the portal site locally

[brian-rose]

What happened:

I tried to build the portal site locally on my Mac laptop while developing #67. I followed the procedure for this described on our Contributor's Guide to set up and activate a dedicated conda environment and then build the site using sphinx.

I got the following error:

Theme error:
An error happened in rendering the page index.
Reason: TypeError("generate_nav_html() missing 1 required positional argument: 'kind'")
make: *** [html] Error 2

What you expected to happen:

The site should build normally without error.

Minimal Complete Verifiable Example:

From repository root directory:

cd content
conda env create -f ../ci/environment.yml
conda activate pythia
make html

Anything else we need to know?:

Environment:

• Python version: 3.9.2
• Sphinx version: 3.5.4
• conda version: 4.9.2
• Operating System: macOS Catalina 10.15.7
• Install method (conda, pip, source): conda, as described above

[ktyle]

@brian-rose I get the same error on our Linux server "lore" ... same environment save the OS, which is a RHEL7-like Linux OS.

[brian-rose]

I was curious why we're getting this build error but the builds on readthedocs are working.

I see now that readthedocs is using requirements.txt to define its python / sphinx environment and doesn't touch ci/environment.yml at all. So the two build environments are inconsistent with each other, which is not ideal.

Looking more closely, I see that ci/environment.yml seems to have extraneous stuff, including pydata-sphinx-theme which I don't think we're using at all.

[brian-rose]

The error goes away when I remove extraneous stuff from ci/environment.yml and make it consistent with requirements.txt

I will shortly submit a PR to fix this.

Longer term, I think we should base the readthedocs build on conda so it's consistent with our own local build instructions. That way we'll avoid this kind of bug in the future.

[ktyle]

Yep, I can confirm as well ... in my case, I removed the pydata-sphinx-theme and then "make html" ran to completion.