Readthedocs vs Github pages

Discussing the best way to implement feature X
Post Reply
User avatar
Johannes
Site Admin
Posts: 159
Joined: 21 Jul 2018, 12:52
Location: UC Berkeley

Readthedocs vs Github pages

Post by Johannes »

Hi all,

so far, I had hosted the documentation on https://tenpy.github.io with github pages.

I have now tried to setup the documentation on https://tenpy.readthedocs.io as well, which is an awesome place hosting documentation for many, many python packages (and other stuff as well).
The nice thing there is that they have continuous integration, i.e. automatically update the docs after each new push to github.
Moreover, it supports keeping multiple versions of the documentation, i.e, you can still look up the doc of version 0.5.0 if a new version gets released.
They also have a different theme.

In contrast, for the github pages I had to setup an updating process myself, which is not so reliable and fast, and it can only host a single snapshot of the documentation.

Which one do you like better?
Should we update the README to link to readthedocs?

EDIT: corrected links

User avatar
Johannes
Site Admin
Posts: 159
Joined: 21 Jul 2018, 12:52
Location: UC Berkeley

Re: Readthedocs vs Github pages

Post by Johannes »

Readthedocs currently includes advertisement, but we could opt-out of that.

User avatar
Johannes
Site Admin
Posts: 159
Joined: 21 Jul 2018, 12:52
Location: UC Berkeley

Re: Readthedocs vs Github pages

Post by Johannes »

@Leon, @mpsforphysics , @JakobUnfried do you have any preferences?

Leon
Posts: 13
Joined: 23 Jul 2018, 09:08
Location: University of Kent

Re: Readthedocs vs Github pages

Post by Leon »

This is brilliant! I much prefer readthedocs for its native updating of the docs. Also, it brings the documentation into a format that is more consistent with other python packages (in my experience). The ads are non-intrusive but I would still recommend opting out (if there are no downsides to that).

PS. the URL in your original post seems broken (links to a non-existing page on the forum, rather than the docs themselves).

User avatar
Johannes
Site Admin
Posts: 159
Joined: 21 Jul 2018, 12:52
Location: UC Berkeley

Re: Readthedocs vs Github pages

Post by Johannes »

Okay, I paid for the Gold membership of readthedocs to remove the ads (That's the drawback, it costs money. But I don't mind supporting ReadTheDocs with a few dollars a month, their service to the community is great :) )
I've also updated the references from within the TeNPy repository and the links in this forum (if they use the [tenpy]...[/tenpy] bbcodes) to point to the new documentation.
Moreover, I put a big, orange warning on top of each page on tenpy.github.io to make sure people realize that the documentation moved :D

Post Reply