Page 1 of 1

Readthedocs vs Github pages

Posted: 20 Dec 2019, 02:31
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

Re: Readthedocs vs Github pages

Posted: 20 Dec 2019, 02:41
by Johannes
Readthedocs currently includes advertisement, but we could opt-out of that.

Re: Readthedocs vs Github pages

Posted: 30 Jan 2020, 21:55
by Johannes
@Leon, @mpsforphysics , @JakobUnfried do you have any preferences?

Re: Readthedocs vs Github pages

Posted: 31 Jan 2020, 10:06
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).

Re: Readthedocs vs Github pages

Posted: 07 Feb 2020, 08:18
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