Host documentation on our infra at docs.kiwix.org and docs.openzim.org

[benoit74]

Currently, we build and publish documentation at readthedocs.io, benefiting from their free community tier.

In #45, I've opened the topic of supporting them to remove adds, but unfortunately the price to pay is a bit too high from my PoV since it is 5$/month/project

Should we consider to build and host documentation on our own infra?

The difficult part would be to maintain doc for latest + all pinned versions, just like readthedocs does. readthedocs source code is open at https://github.com/readthedocs/readthedocs.org, but there is barely no documentation about self hosting, I doubt everything is in this repo, and it is probably not totally straightforward to deploy given the webhooks and build workers that are needed.

There is however also an opportunity:

• build a central homepage for all our documentation (currently it is barely possible to easily find all our documentation since they are different projects in readthedocs)
• build documentation even for older versions as a one-shot custom build done manually ; for instance for python-scraperlib, it is tough to rebuild documentation with readthedocs for previous version since readthedocs + mkdoc code/files are not present in the repo in every tagged version ; manually doing with a script backporting thing (without needed to commit them to the repo) is however mostly straightforward

[Popolechien]

@benoit74 Yes in principle, but then how much time would this require, and what does readthedocs do that github does not?

[benoit74]

This is probably about 2 days work to setup on our infra.

Readthedocs automatically maintain / store the doc for all released versions.

Github has nothing for this.

We will need to build something for this on our own if we want to run this on our infra. And it will be less polished in term of dashboard to see what's going on.

[Popolechien]

Stupid question : do we really need versioning (which I though GH had) or is it more of a Best Practice approach?

[benoit74]

Yes we need it, because users need to know how software worked at the version they are using, not the most recent one.