Stop using Read the Docs

[Kodiologist]

Having ads in the manual is extraordinarily tacky. We should probably just host the web versions of Hy and Hyrule's manuals on Arfer.net, where I also host the new Hylang.org. For simplicity, we can serve only the stable release of the manual. We would then just rebuild it as part of the release process.

[chiefnoah]

Why not just use gitlab pages? It's free and supports arbitrary static sites

[Kodiologist]

I'm not familiar with GitLab. What are the advantages of hosting a website on it, compared to a conventional VPS?

[chiefnoah]

Oh oops, I typoed "GitLab". Meant GitHub Pages. It's an optional feature on each repo

[Kodiologist]

I don't think GitHub Pages is a great fit for any static site where the pages are automatically generated, as with Sphinx in the case of our documentation. GitHub only serves what's committed—it can't run a program to generate the pages to serve—so all the generated pages would have to be committed.

[scauligi]

So it looks like there are a few different community plugins for using GitHub Actions to automatically build Sphinx documentation, for example this one which looks like it should be able to build+deploy docs to GitHub Pages, maybe worth looking into?

[Kodiologist]

Hmm, perhaps that sort of use of GitHub Pages is more viable than I thought.

[jquast]

You can support rtd by paying $5/mo, and in return you can remove ads from 3 projects

[atisharma]

I don't much mind where the docs are hosted, so long as the "bus problem" is planned for.

This happened in Void linux, for example, when xtraem disappeared and nobody had the keys.

[Kodiologist]

Yeah, that kind of thing can be painful. For Hy there's some protection in that both Paul and I have most of the credentials.

[goyalyashpal]

• current hylang docs: https://docs.hylang.org/

here's how some others do it:

	site	repo	service
helix	docs.helix-editor.com	book/src/install.md	i thought it was zola or hugo but per its .github/workflow action files seems it is mdbook
wezterm	https://wezfurlong.org/wezterm/	docs/index.md	squid-mkdocs
pandas	http://pandas.pydata.org/pandas-docs/stable/getting_started/install.html	doc/source/getting_started/install.rst	sphinx
matplotlib	https://matplotlib.org/stable/index.html	doc/index.rst
numpy	https://numpy.org/doc/stable/user/index.html#user	doc/source/user/index.rst

Docusaurus https://librearts.org/2023/07/week-recap-3-jul-2023/#freecad:~:text=Docusaurus

[Kodiologist]

Read the Docs gave me a lot of grief today while I was releasing Hy 0.27.0. Its implicit default dependencies had some weird interaction with the dependencies we ask for, which led to pip spending an hour in fruitless search to satisfy impossible requirements. I kept trying to cancel documentation-building jobs and the cancellation request would be ignored or jobs would spontaneously reactivate. Even if things had worked as-is, Read the Docs is making a breaking change requiring new configuration files this September. I added the configuration file and got things working again, but overall, my appetite for escaping from Read the Docs has certainly increased.

[thomasmatecki]

This seems pretty straightforward, see #2485: https://thomasmatecki.github.io/hy/. There are some changes to the repository settings that need to happen: https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site

The "book" theme is an experiment. I'll can switch back to the read the docs theme if we want to go ahead this this.

Also there will be links to track down and fix.

[goyalyashpal]

Its implicit default dependencies had some weird interaction with the dependencies we ask for, which led to pip spending an hour in fruitless search to satisfy impossible requirements. - @ Kodiologist at https://github.com/hylang/hy/issues/2417#issuecomment-1624250091

do you think micromamba's powerful dependency solver could have helped with that?

[Kodiologist]

No idea. I find packaging and dependency-management issues annoying and so I do the minimum.

[Kodiologist]

I've picked this up recently. My approach is to integrate the process of building the Hy and Hyrule manuals into hyhomepage and host them the same way as the rest of hylang.org.