Issues when building documentation locally

[mlincett]

A few issues and warnings are encountered when trying to build the documentation locally. I suggest we add to the README the instructions to do it, so we can better discriminate the issues from user (me in this case) mistakes.

Specification of SOURCEDIR

Running make inside the docs directory fails with:

Configuration error:
config directory doesn't contain a conf.py file ([...]/docs)

Changing SOURCEDIR = ./source in the Makefile solves the issue, but apparently this is not a problem for Read the Docs? What is the correct procedure for a local build?

Dependencies

myst_nb and sphinx_rtd_theme should be included among flarestack requirements (although there is a deprecation warning for sphinx_rtd_theme so maybe its replacement should be considered.

Warnings

There are a bunch of other warnings but they do not seem blocking. We can take care of those gradually.

[mlincett]

I understand the Makefile is not used by Read the Docs, so the first point can be easily addressed.

I see that the dependencies for the docs building are specified in the pyproject.toml. I think that the proper poetry syntax can install flarestack with the proper dependencies, but I cannot figure which is it (still new to poetry).

[mlincett]

Installing with:

poetry install --with docs
poetry add

does the trick. I am gonna update the README.md with this.

Also thinking of removing docs/source/getting_started.rst since it is currently unused.

Summary of TODOs:

• [x] update README with how to build the documentation;
• [x] update docs/Makefile
• [x] remove docs/source/getting_started.rst
• [x] set language = "en" in docs/source/setup.py

[JannisNe]

So I have not used the Makefile at all. I use

sphinx-build -b html docs/source/ docs/build/html

So we could add this to the documentation and drop the Makefile.

[mlincett]

sphinx-build -b html docs/source/ docs/build/html

Alright. I suggest we retire also the make.bat then (I guess both were a byproduct of sphinx-init).