search

ELEKTRONN / elektronn3

A PyTorch-based library for working with 3D and 2D convolutional neural networks, with focus on semantic segmentation of volumetric biomedical image data
MIT License
160 stars 27 forks source link

readthedocs page with auto-generated API documentation #16

Closed mdraw closed 6 years ago

mdraw commented 6 years ago

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 https://github.com/ELEKTRONN/ELEKTRONN2/pull/1 for an example of the initial readthedocs set-up.

mdraw commented 6 years ago

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: image 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 https://github.com/ELEKTRONN/elektronn3/blob/91c0b14d5c7ccd0d150cf1e1d68bf42da17eea52/docs/sphinx-requirements.txt#L3-L4 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: https://github.com/rtfd/readthedocs.org/issues/1767

mdraw commented 6 years ago

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 https://github.com/rtfd/readthedocs.org/issues/3829 is resolved. Also related: https://github.com/rtfd/readthedocs.org/issues/3769.

mdraw commented 6 years ago

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.