Repository: hylang/hy

Issue:
Stop using Read the Docs
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](http://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.


Discussion:
Why not just use gitlab pages? It's free and supports arbitrary static sites
I'm not familiar with GitLab. What are the advantages of hosting a website on it, compared to a conventional VPS?
Oh oops, I typoed "GitLab". Meant GitHub Pages. It's an optional feature on each repo
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.
So it looks like there are a few different [community plugins](https://github.com/marketplace?type=actions&query=Sphinx) for using GitHub Actions to automatically build Sphinx documentation, for example [this one](https://github.com/marketplace/actions/sphinx-to-github-pages) which looks like it should be able to build+deploy docs to GitHub Pages, maybe worth looking into?
Hmm, perhaps that sort of use of GitHub Pages is more viable than I thought.
You can support rtd by paying $5/mo, and in return you can remove ads from 3 projects
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.
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.
* current hylang docs:
https://docs.hylang.org/

here's how some others do it:


[zola]: https://www.getzola.org/documentation/getting-started/overview/
[hugo]: https://gohugo.io
[hx-gh-action]: https://github.com/helix-editor/helix/blob/master/.github/workflows/gh-pages.yml

[squid-mkdocs]: https://squidfunk.github.io/mkdocs-material/
[sphinx]: http://sphinx-doc.org/


|  | site | repo | service
-- | -- | -- | -- 
helix | [docs.helix-editor.com](https://docs.helix-editor.com/master/print.html) | [book/src/install.md](https://github.com/helix-editor/helix/blob/master/book/src/install.md) | i thought it was [zola] or [hugo] but per its [`.github/workflow` action files][hx-gh-action] seems it is `mdbook`
wezterm | https://wezfurlong.org/wezterm/ | [docs/index.md](https://github.com/wez/wezterm/tree/main/docs/index.md) | [squid-mkdocs]
pandas | http://pandas.pydata.org/pandas-docs/stable/getting_started/install.html | [doc/source/getting_started/install.rst](https://github.com/pandas-dev/pandas/blob/main/doc/source/getting_started/install.rst) <td rowspan="3"> [sphinx] </td>
matplotlib | https://matplotlib.org/stable/index.html | [doc/index.rst](https://github.com/matplotlib/matplotlib/blob/main/doc/index.rst) 
numpy | https://numpy.org/doc/stable/user/index.html#user | [doc/source/user/index.rst](https://github.com/numpy/numpy/blob/main/doc/source/user/index.rst)

Docusaurus
https://librearts.org/2023/07/week-recap-3-jul-2023/#freecad:~:text=Docusaurus
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.
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.



> 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?

[micromamba]: https://mamba.readthedocs.io
No idea. I find packaging and dependency-management issues annoying and so I do the minimum.
I've picked this up recently. My approach is to integrate the process of building the Hy and Hyrule manuals into [hyhomepage](https://github.com/hylang/hyhomepage) and host them the same way as the rest of hylang.org.

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,20 +1,14 @@
-# This file is execfile()d with the current directory set to its containing dir.
+import os, re, sys, time, html
 
-import html
-import os
-import re
-import sys
-import time
+sys.path.insert(0, os.path.abspath('..'))
 
-sys.path.insert(0, os.path.abspath(".."))
+import hy; hy.I = type(hy.I)  # A trick to enable `hy:autoclass:: hy.I`
 
 extensions = [
-    "sphinx.ext.napoleon",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.autodoc",
-    "sphinx.ext.viewcode",
-    "sphinxcontrib.hydomain",
-]
+    'sphinx.ext.napoleon',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autodoc',
+    'sphinxcontrib.hydomain']
 
 import warnings; import sphinx.deprecation as SD
 for c in (SD.RemovedInSphinx60Warning, SD.RemovedInSphinx70Warning):
@@ -22,64 +16,33 @@
 
 from get_version import __version__ as hy_version
 
-# Read the Docs might dirty its checkout, so strip the dirty flag.
-hy_version = re.sub(r"[+.]dirty\Z", "", hy_version)
-
-templates_path = ["_templates"]
-source_suffix = ".rst"
-
-master_doc = "index"
-
-# General information about the project.
-project = "hy"
-copyright = "%s the authors" % time.strftime("%Y")
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = ".".join(hy_version.split(".")[:-1])
-# The full version, including alpha/beta/rc tags.
+project = 'Hy'
+copyright = '%s the authors' % time.strftime('%Y')
+html_title = f'Hy {hy_version} manual'
+version = '.'.join(hy_version.split('.')[:-1])
+  # The short dotted version identifier
 release = hy_version
-hy_descriptive_version = html.escape(hy_version)
-if "+" in hy_version:
-    hy_descriptive_version += " <strong style='color: red;'>(unstable)</strong>"
-
-exclude_patterns = ["_build", "coreteam.rst"]
-add_module_names = True
-
-pygments_style = "sphinx"
-
-import sphinx_rtd_theme
-
-html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
-
+  # The full version identifier, including alpha, beta, and RC tags
+
+source_suffix = '.rst'
+master_doc = 'index'
+exclude_patterns = ['_build', 'coreteam.rst']
+
+html_theme = 'nature'
+html_theme_options = dict(
+    nosidebar = True,
+    body_min_width = 0,
+    body_max_width = 'none')
+html_css_files = ['custom.css']
+html_static_path = ['_static']
 html_use_smartypants = False
+html_copy_source = False
 html_show_sphinx = False
 
-html_context = dict(
-    hy_descriptive_version=hy_descriptive_version)
+add_module_names = True
 
-highlight_language = "hylang"
+highlight_language = 'hylang'
 
 intersphinx_mapping = dict(
-    py=("https://docs.python.org/3/", None),
-    hyrule=("https://hyrule.readthedocs.io/en/master/", None),
-)
-
-import hy
-hy.I = type(hy.I)  # A trick to enable `hy:autoclass:: hy.I`
-
-
-# ** Sphinx App Setup
-
-
-def setup(app):
-    app.add_css_file("overrides.css")
+    py = ('https://docs.python.org/3/', None),
+    hyrule = ('https://hyrule.readthedocs.io/en/master/', None))


Test patch: