Improving readthedocs instructions

[edublancas]

Context

I'm working on a project with jupyter-book, so I went through the tutorials to deploy it on readthedocs.io. However, I encountered a few difficulties, so I'm sharing my feedback. Hopefully, this can help newcomers get it up and running faster!

Note that I created a new book with jupyter-book create mynewbook/, then, copied the configuration from here and attempted to deploy to readthedocs.

Proposal

My first attempt failed, readthedocs showed the following error:

Command:

 /home/docs/checkouts/readthedocs.org/user_builds/notebooks-academy/envs/latest/bin/python -m pip install --upgrade --upgrade-strategy eager --no-cache-dir .[sphinx]

Error:

ERROR: Directory '.[sphinx]' is not installable. Neither 'setup.py' nor 'pyproject.toml' found.

It wasn't clear why readthedocs wanted to install my project as a package. After reading readthedocs documentation, I realized that this part:

python:
  install:
    - method: pip
      path: .
      extra_requirements:
      - sphinx

Tells the build system to install the project as a package. I guess that in most cases, users won't have a setup.py so it'd be better if the sample configuration looks like this:

python:
  install:
    - requirements: requirements.txt

Once I fixed that I encountered a second error

Command:

/home/docs/checkouts/readthedocs.org/user_builds/notebooks-academy/envs/latest/bin/python -m sphinx -T -E -W --keep-going -b html -d _build/doctrees -D language=en . _build/html

... a few irrelevant lines

ERROR: Execution Failed with traceback saved in /home/docs/checkouts/readthedocs.org/user_builds/notebooks-academy/checkouts/latest/website/_build/html/reports/notebooks.log
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 25%] intro
writing output... [ 50%] markdown
writing output... [ 75%] markdown-notebooks
writing output... [100%] notebooks

generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 1 warning.
Updating searchtools for Read the Docs search... [etoc] missing index.html written as redirect to 'intro.html'

It took me a while to figure this one out because the last line of the error does not show any useful messages. The error cause is hidden a few lines above: ERROR: Execution Failed with traceback saved...

Then, I realized that the jupyter-book build command generates a sample notebook that requires matplotlib to run, since it's missing, it breaks. Here I suggest including in the docs that the user should ensure that all the dependencies required to run the notebooks are included in the requirements.txt file.

Happy to open a PR if the maintainers think these recommendations should be incorporated to the docs.

Tasks and updates

No response

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[AdamRJensen]

Very much agree that the example should preferably use:

python:
  install:
    - requirements: requirements.txt