sfstoolbox/theory

Not all figures were build

Closed this issue · 5 comments

hagenw commented

At the moment only the first figure automatically generated from python code is build:
http://sfstoolbox.org/en/latest/#plane-wave
All remaining figures are missing, e.g. http://sfstoolbox.org/en/latest/#point-source

Do we have to change something?

mgeier commented

According to the build logs (http://readthedocs.org/projects/sfs/builds/5089807/), this looks very much like the NumPy "norm" error: sfstoolbox/sfs-python#11, for which I committed a work-around in sfstoolbox/sfs-python@d640cd6, which isn't yet released.

It seems like currently RTD uses the exact version of NumPy that is broken, see http://packages.readthedocs.io/en/latest/deb/.

I see three possible solutions:

  1. using numpy!=1.11.0 in requirements.txt and hope that NumPy can be installed on RTD via pip
  2. using conda, which has much newer packages (e.g. matplotlib 2.0). For usage see
    https://github.com/sfstoolbox/sfs-python/blob/master/readthedocs.yml and
    https://github.com/sfstoolbox/sfs-python/blob/master/doc/readthedocs-environment.yml
  3. making a SFS-python release

BTW, You should be able to get rid of the local copy of plot_directive.py, since matplotlib 1.5 is now available on RTD (even when not using conda).

hagenw commented

Thanks.

Solution 1. works.
Regarding solution 2.: this is interesting as we need a recent version of sphinx for the splitting up of the document (#20). The problem is that sfs cannot be installed by conda. So I created in addition to readthedocs.yml and readthedocs-environment.yml a requirements.txt containing only sfs. But it does not work: https://readthedocs.org/projects/sfs/builds/5093711/.

plot_directive.py can indeed be removed, thanks for pointing this out.

mgeier commented

It should be possible to require a more recent version of Sphinx with solution 1 as well, see e.g. https://github.com/sfstoolbox/sfs-python/blob/master/doc/requirements.txt.

If you choose solution 2, you can't use requirements.txt.
Luckily, it's very easy to require pip packages in a conda environment. I've documented this there: http://nbsphinx.readthedocs.io/en/latest/usage.html#Using-conda.

hagenw commented

I have now chosen solution 2 and everything works fine.

Regarding the requirements.txt file, there is also a version in sfs-python. I guess we can delete it:
https://github.com/sfstoolbox/sfs-python/blob/master/doc/requirements.txt

mgeier commented

Great!

The file requirements.txt is indeed not needed for RTD, but it can still be used by anyone who wants to create the documentation locally, as described here: http://python.sfstoolbox.org/en/latest/CONTRIBUTING.html.

Ideally, conda should be able to somehow "include" the requirements.txt in order to avoid duplication, but AFAIK, this is not possible.
conda/conda#3983
conda/conda#720

I guess we can remove the jinja2 and pygments requirements though, because they should be installed by sphinx anyways ... I don't remember why I put them there in the first place ...