Upload Python documentation to ReadTheDocs

[cthoyt]

This is a follow-up to #52. Now that the documentation can be built with sphinx, the best way to get it to the masses is with ReadTheDocs

Though the python community usually uses docs instead of doc as the name for the documentation folder, it should be smart enough to find the conf.py file and build the documentation without much configuration at all.

I tested it myself at http://cthoyt-b2.readthedocs.io/en/latest/ and it seems to work. I don't mean to make finding documentation confusing, so I'll take this down as soon as you've seen it and got your own vanity URL secured :)

Update ReadTheDocs pulled the minieigen repository and seemed to choose its documentation instead. There's a setting in the web service, or can be encoded in a .readthedocs.yml file to point to exactly the correct conf.py

[ofloveandhate]

thanks so much for your quick response! i guess i have a few questions:

• should my package name pybertini be called just bertini -- is the extra py too much?
• is the readthedocs vanity name supposed to match the name of the package, ideally?

[cthoyt]

I suggest using either PyBertini or pybertini depending on which capitalization you like (I prefer the first). This makes it obvious that this is the python extension to something else.

Whichever you choose to keep as your package name, I would also suggest using the same for the vanity URL on readthedocs. Unfortunately, I think it's impossible to change it after you create it, so be very sure!

[ofloveandhate]

i think my situation is complicated. because the pybertini bindings depend on the bertini2 c++ core having been installed (and the c++ part of the python bindings, too), and also since i depend on autodoc from sphinx -- which depends in turn on the ability to import pybertini -- the documentation will be a trick to get properly hosted on readthedocs.io

do you have any suggestions?

[cthoyt]

ReadTheDocs is built to work incredibly well with sphinx - in fact you've already configured it correctly to not need to import pybertini at all becuase of these lines in conf.py: https://github.com/bertiniteam/b2/blob/4293330663c5635e3f6c48574f9b660ee7df9c73/python/docs/source/conf.py#L27-L28

I remember having some problems when I was using some weird C++ dependencies that were necessary for the readline package that was a dependency of a dependency and so on... They've got support for this here: http://docs.readthedocs.io/en/latest/faq.html#i-get-import-errors-on-libraries-that-depend-on-c-modules

I'm not exactly sure where the C++ bindings come in, but you might be able to mock just that part. Are the docs in the C++ templates for boost, the C++ code, or the python code?

[ofloveandhate]

I have at least four sets of documentation I maintain as part of Bertini2

1. The C++ core, done with doxygen. 🍇 This docset has nothing to do with PyBertini, and needs to be hosted separately. But see here for a SO post on how to get RTD to host doxygen-based projects.
2. The hidden _pybertini Python bindings using Boost.Python. 🍇 Docstrings for exposed functions and classes are written into the library by compiling the bindings. Moving the docstrings into PyBertini so that the core and _pybertini don't need to be compiled is possible, but it means maintaining a third layer of touching every single function and class that is exposed. Since I have little more time to devote to this project than I already do, this is not an option for me. Putting the docstrings in the C++ to Python layer reduces the complexity of the project significantly, as does Sphinx's autodoc feature.
3. The pure Python layer, pybertini. 🍇 Basically just a bunch of imports of stuff from _pybertini, and some mild restructuring. Docstrings for the files and some other bits live in the .py files, but the actual narrative documentation for PyBertini (tutorials, explanations, etc) is in Sphinx.
4. My GitHub wiki

So, my questions are about ensuring the parts of 2 make their way through part 3 to the hosted docs. I have not been successful in getting ReadTheDocs to show PyBertini documentation instead of minieigen. So, I haven't been able to test whether part 2 already does and I am thinking about a problem that doesn't exist, ha.

🦄

[ofloveandhate]

• See a b2/python/src file for an example of how docstrings are created in C++.

• See a b2/python/docs restructured text file providing narrative, and bringing in the documentation from the pure-python part of pybertini.

• See a pure python file in b2/python/pybertini which imports stuff from the C++-Python glue that lives in b2/python/include and b2/python/src and is in the private namespace _pybertini

• See an issue for GalSim which indicated this was the path to go down. It absolutely is, the entire pybertini library is much more sensible since I restructured to mirror GalSim.

[ofloveandhate]

i was able to get readthedocs to use my own requirements.txt file, and generate the documentation for pybertini, from a branch on my fork of b2

• github branch

• rtfd for the branch

it looks as expected, with the theme i selected, etc. however, the actual function documentation is missing because the library can't be correctly imported, since the C++ core is missing.

i think a solution might be to use a subdomain i control, and use jenkins to upload new versions when i commit. this is a less satisfying solution, however, because i miss the integration wth the python community.

thanks for any ongoing communication!!! 🌈

[ofloveandhate]

while i haven't been able to get ReadTheDocs to work for me the way i want, I have been able to finally get my build server to upload files automatically. so, now i just need to get my doc server completed, and i can point to the external place from ReadTheDocs. somehow.

[ofloveandhate]

readthedocs still isn't happening, so i need to implement a redirect or something. i have pybertini documentation hosted at doc.bertini2.org/pybertini. the c++ core documentation is similarly at doc.bertini2.org/core.

[ofloveandhate]

the pybertini documentation is now built automatically upon commit via jenkins, and published at doc.bertini2.org.

i am closing this, and marking as not going to do, because of the challenges with readthedocs and a c++ library.

if you are reading this and know how to make readthedocs.io redirect from their servers to mine from my project name, or how to automatically update a documentation-only repo from jenkins so that readthedocs can build those machine-generated commits, or some other tricky way of making this magic happen, please please please 🍨.🔝(🍒) , contact @ofloveandhate and let her know.