Readthedocs.org: pages missing from pyArango

[dothebart]

Details

As reported by a user via https://github.com/ArangoDB-Community/pyArango/issues/146 it seems a page went away; Meanwhile its there again. Is there any way to track this down or any more reasoning?

one of the pages in question was:
https://pyarango.readthedocs.io/en/latest/database/

[stsewd]

it seems a page went away

Do you mean it was 404? or the docs from the docstrings weren't showed?

[dothebart]

maybe @aernesto can answer this better, since I'm only forwarding this.

[aernesto]

@stsewd It was not 404. The docs from the docstrings weren't showed.

[stsewd]

I can only think that an error happened when running the install package step.

Here for example

https://readthedocs.org/projects/pyarango/builds/9130011/

Then the other successful build was run in the same server, where we cache the previous _half installed package_

You can clean all cache files going\ to versions -> edit -> wipe

And btw, I don't see your package is being installed (./setup.py install or pip install .) or using sys.path https://github.com/ArangoDB-Community/pyArango/blob/7181ff9e99070ae41e57c013ae1042df9588025a/pyArango/doc/source/conf.py#L23

[aernesto]

Thank you @stsewd
Just in case it is useful, some pages are down again (see this one for instance).

[stsewd]

I think this is because you are not installing your package or given access to it with sys.path.

This is a log from the last build

WARNING: autodoc: failed to import module 'collection' from module 'pyArango'; the following exception was raised:
No module named 'pyArango'

See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

But I'm curious why it sometimes success :thinking:

[tariqdaouda]

That might be because I am trying things at the moment. This is a new error, never seen it before.

[stsewd]

Try with

sys.path.insert(0, os.path.abspath('../../..'))

[tariqdaouda]

Thanks @stsewd , @dothebart and @aernesto got it working! Not sure exactly what happened, all pages display now on both stable and latest.

sys.path.insert(0, os.path.abspath('../../..'))

Does not seem to change anything, it is on on master and off on dev, both work.

EDIT: I've uncommented it on both branches just in case.

[stsewd]

You should try wiping the version first, just in case to remove the cache. That will give you a more deterministic result

https://docs.readthedocs.io/en/stable/guides/wipe-environment.html

[tariqdaouda]

That's what I did this time, systematically wiping in between changes. Thanks for pointing out the wipe button, I did not see it and assumed that the wiping was automatic.

[stsewd]

Just in case, I build your docs locally and with the current configuration I can't see the docs.

I tested it with python setup.py install to install the package but there are some C dependencies that probably are not in the servers (this makes the build to fail in rtd)

I made it work with (this is necessary so autodoc knows where is your package)

sys.path.insert(0, os.path.abspath('../../..'))

+ installing the requirements needed in those files:

pip install 'requests>=2.7.0' 'future' 'datetime' 'grequests' 'gevent'

(this is necessary because autodoc imports your files for real, so you need all the packages installed)

So in order to replicate that in read the docs, it's more easy to create a configuratio file.
Please take a look at the rtd configuration file https://docs.readthedocs.io/en/stable/config-file/v2.html

# .readthedocs.yml
version: 2

# Build documentation in the docs/ directory with Sphinx
sphinx:
  configuration: pyArango/doc/source/conf.py

python:
  version: 3.7
  install:
    - requirements: pyArango/doc/requirements.txt

And you should create a requirements file pyArango/doc/requirements.txt with

requests>=2.7.0
future
datetime
grequests
gevent

[tariqdaouda]

Thanks for your help, this definitely makes everything clearer.

[dothebart]

Thank you very much for helping us to understand and fix this.