Readthedocs

[iosonofabio]

Trying out adaptations to build on RTD @ntamas

Current status:

• build set up
• virtual environment config-ed
• dependencies installed
• C core builds
• Python package builds
• Python package installs into virtual env
• Modularizing pure Python works
• Sphinx starts
• pydoctor finishes
• sphinx finishes
• output html files copied correctly to output folder
• docs are live on RTD
• get rid of Jekyll headers and set theme
• polish appearance
• tidy up code, esp. make sure distinct versions/branches/tags all have correct links
• add RTD link checker
• correct broken internal and external links
• improve homepage
• link older docs on homepage

https://readthedocs.org/projects/igraph/builds/

Here the output:

https://igraph.readthedocs.io/en/latest/

[iosonofabio]

This now builds successfully on RTD after some hack due to race conditions between pydoctor and the RTD sphinx extension (sigh!). First successful build artifact here: https://igraph.readthedocs.io/en/latest/

Now I'll move on to improving appearance and tidying up code.

[iosonofabio]

This is going quite well. Our docs are now deploying nicely to RTD including the API via pydoctor. Sphinx's linkcheck requires a recent version of requests to establish decent SSL handshakes with one (!) external link, so I'm trying to update that. In any case, it's not critical: the linkcheck works nicely on my machine.

[iosonofabio]

okay, I think this one's ready do merge AFAICT

[szhorvat]

How does this work exactly? Does it regularly re-build the docs even for the dev version? If yes, that's quite nice.

Now that it's merged, can it be connected to the official repo, or do we need to wait for the 0.10.2 release with that? I see now it's connected to @iosonofabio 's repo (including the Edit on GitHub links) and has a big fat warning about not being official. https://readthedocs.org/projects/igraph/

I find it more pleasant to browse than the igraph.org ones though.

[ntamas]

I've talked about this briefly with @iosonofabio after the end of today's dev meeting. He still wants to get the Sphinx Gallery stuff done so we can publish the examples with that. Once this is done, we can remove the warning.

As for the switch, there are two options:

1. We do the switch in parallel to 0.10.2 and then there's a clear situation: if you want the docs before 0.10.2, go to the archive on igraph.org, otherwise go to readthedocs.org.
2. We do the switch after 0.10.1 but before 0.10.2. In that case, people who want the official 0.10.1 docs should still go to the homepage, but people searching via Google will find an "alternative" set of documentation on readthedocs.

I'd prefer option 1 as it causes less confusion.

[iosonofabio]

As Tamas wrote, I'd be happier with option 1. I'll re-rig the RTD config against the correct repo etc. in the next 2-3 days.

Happy to hear you like it!