readthedocs page with auto-generated API documentation
mdraw opened this issue · 3 comments
Once #15 is resolved, we should create a page on https://readthedocs.io to host elektronn3 documentation, similar to https://elektronn2.readthedocs.io/en/latest/. See ELEKTRONN/ELEKTRONN2#1 for an example of the initial readthedocs set-up.
I have set up https://elektronn3.readthedocs.io/ with a webhook to build and update docs on this page, but the build pipeline fails due to memory limitations:
This is probably related to the large doc requirements like PyTorch. I already tried slimming down those requirements by using CPU-only wheels of PyTorch in
elektronn3/docs/sphinx-requirements.txt
Lines 3 to 4 in 91c0b14
but apparently this is not enough. I haven't had success with mocking expensive requirements during documentation builds yet, but theoretically this should be a solution.
Related: readthedocs/readthedocs.org#1767
My attempt at using a conda-based documentation build setup in the rtd-test branch fails due to a different issue: Sphinx >=1.7.1 has a bug that makes the build fail with the following message:
sphinx-build: error: argument -d/--maxdepth: invalid int value: '_build/doctrees-readthedocs'
This does not happen when using sphinx 1.7.0 or earlier.
(The same issue happens in ELEKTRONN2 currently. That's the reason why ELEKTRONN2 docs are out of date.)
I tried to fix this by pinning sphinx to 1.7.0 in the builder, but there is a second issue: Sphinx version pinning is currently ignored by readthedocs. We will probably have to wait until readthedocs/readthedocs.org#3829 is resolved. Also related: readthedocs/readthedocs.org#3769.
After merging #24, there is a new kind of error in the rtd builder: https://readthedocs.org/projects/elektronn3/builds/7500776/ :(
Let's hope that this is just a temporary server issue. The automatic online build was successful in a private area of the website, so I have no idea what else could be wrong.