Documentation not building reliably

[martinstringer]

Describe the bug

Documentation is not building, at least not on my system.

To Reproduce

Try building the documentation.

Expected behaviour

On my system, the build process stopped multiple times due to a series of missing requirements. Some were ok to trace and install, but we should add instructions to MUSE docs section 3.4.4 so that new users do not waste time.

Eventually I hit requirements for out-of-date versions:

058: RuntimeWarning: You are using an unsupported version of pandoc (3.1.11.1). Your version must be at least (1.12.1) but less than (3.0.0).

And eventually:

Notebook error: AttributeError in advanced-guide/extending-muse.ipynb: module 'jinja2.utils' has no attribute 'escape'

Could we please update docs/requirements.txt and/or other files so that the documentation builds for users first time?

Context

I needed to build the docs locally to correct the incorrect equations noted in issue #223, but then used up all my time chasing requirements for building the docs. This issue is therefore blocking progress on #223.

[dalonsoa]

Looking into this now. Can you indicate:

• Version of Python
• Operative System

[dalonsoa]

@martinstringer , I need some more info here. Running the following in a fresh virtual environment with the code in the develop branch in Ubuntu with python 3.9.18 and pandoc 3.1.11.1 runs out of the box without any error, just a few warning that disappear after running the documentation step a few times, which is often required, anyway:

# Create the virtual environment
python -m venv .venv
# Activate the environment
. .venv.bin/activate
# Install dependencies, documentation 3.4.1
python -m pip install -e .[dev,doc]
# Build the documentation (run 3 times), documentation 3.4.4
python -m sphinx -b html docs docs/build

In summary, could you provide the following?

• Python version
• Operative system
• What virtual environment you use, venv or conda?
• How did you installed the dependencies?
• If you installed them with pip, as instructed, run python -m pip list and provide the resulting list
• Provide the complete error message you are getting when trying to build the documentation

[dalonsoa]

@martinstringer , do you have any update on this?

[martinstringer]

Thank you for your efforts Diego. Sorry that I was not able to get back to MUSE until today due to necessary focus on other projects.

The docs do now build on my computer. However, just for completeness, I will ask some students to also try building it. Then we will have a balanced sense of what (f anything) needs to be added to the documentation to help future users avoid pitfalls.

Perhaps we could leave the issue open until that test has been carried out?

[dalonsoa]

Sure!

If the documentation is unclear or plainly wrong, it clearly needs updating, so let's keep an eye on that.