online docs on readthedocs

[GoogleCodeExporter]

It would be nice to have docs available on readthedocs, which is quickly 
becoming a de-facto standard place for open source documentation. 

However, readthedocs cannot build C-extensions etc so one has to do other 
things to make it work. At the moment, our docs do not build there:

https://readthedocs.org/projects/mdanalysis/

Does someone want to look into this in more detail?

See also Issue 134.

Original issue reported on code.google.com by orbeckst on 27 May 2014 at 8:58

[GoogleCodeExporter]

How sure are we that the 'latest' readthedocs build is actually pulling from 
develop rather than master? I tried the prescribed fix for the C dependency 
problem in sphinx conf.py and not only did it fail, but the extra code I added 
did not affect the line number in the traceback, suggesting the source used for 
building is not the latest develop. Perhaps the owner has to adjust some 
setting for the 'build button' to pull from develop?

It's also probably not ideal that testing the readthedocs build requires 
pushing local commits--unless there's an offline way to do the build I'm not 
aware of.

Original comment by tyler.je.reddy@gmail.com on 11 Jun 2014 at 7:07

[GoogleCodeExporter]

Tyler,

can you sign up on readthedocs and email me your username there so that I can 
give you admin access?

I changed the settings (Admin: Advanced Settings: Default Branch) so that 
'develop' is now being used.

You could change 'Default Branch' to a google code testing branch, e.g. 
testing-docs and try out as much as you like on that branch. You can then merge 
or cherry-pick into develop and the history remains clean.

Oli

Original comment by orbeckst on 11 Jun 2014 at 11:21

[GoogleCodeExporter]

I now have a branch that will pass the build on readthedocs 
(http://mda-test.readthedocs.org/en/test_readthedocs/). However, it appears to 
only pass the build because I've done two things (below) which ultimately mean 
most modules / pages have a lot of missing content: 

1) Mocked import of entire MDAnalysis parent module (for Mock() see: 
http://read-the-docs.readthedocs.org/en/latest/faq.html)
2) Manually fed in the __version__ string (which is not a string at the 
moment--probably because of #1)

My current idea to get more complete docs is to only selectively mock the 
modules in MDAnalysis that have C module dependencies. Do we have a 
comprehensive list of MDAnalysis modules that contain C dependencies? We may be 
able to do this programatically by working on the sys.modules dictionary, which 
is where the mocking is done.

Alternatively (or, in addition), it might be a decent idea to take a look at 
the sphinx conf.py file in well-established open source Python projects with C 
dependencies where readthedocs seems to work well.

Original comment by tyler.je.reddy@gmail.com on 15 Jun 2014 at 6:17

[GoogleCodeExporter]

As it stands Oli and I have noted that several major Python projects have not 
been able to overcome this C-library dependence problem for readthedocs so I'm 
closing the issue.

Original comment by tyler.je.reddy@gmail.com on 19 Jun 2014 at 10:19

• Changed state: WontFix

[GoogleCodeExporter]

Original comment by dot...@gmail.com on 18 Mar 2015 at 12:09

• Changed state: Started

[GoogleCodeExporter]

I gave building the docs on readthedocs a shot, but yeah, there is no way 
around the problem of having C-compiled components in the package itself if we 
want autodoc to grab docstrings. It wouldn't be a problem if MDAnalysis only 
had dependencies that had C-compiled components, but it needs to be built and 
installed by readthedocs and no method is exposed for making it skip the build 
process (if someone else finds otherwise, there may be hope).

My suggestion is to forget readthedocs as a solution until this is no longer a 
problem, if ever. Hosting docs for releases as gh-pages on github is probably 
the best solution at the moment. If we end up doing continuous integration 
through a Jenkins server, then we might be able to make doc generation and 
pushing part of the process for master and develop branches.

Original comment by dot...@gmail.com on 29 Mar 2015 at 7:39

[GoogleCodeExporter]

Original comment by dot...@gmail.com on 29 Mar 2015 at 7:39

• Changed state: WontFix