More website love (#1593)

* Move files/directories out of the website subdirectory. (The entire
documentation dir is the website content.)
* Build the website and the package docs separately. They're still
deployed together in that the package docs are under
opendylan.org/package/ but they use separate search indexes. There will
be more tweaks needed to get this exactly right.
* Fix lots of build and linkcheck errors, some new some pre-existing.

.github/workflows/build-deploy-documentation.yml

@@ -31,12 +31,12 @@ jobs:
 
       - uses: ammaraskar/sphinx-action@master
         with:
-          pre-build-command: "echo furo >> documentation/website/requirements.txt"
-          docs-folder: "documentation/website"
+          pre-build-command: "echo furo >> documentation/requirements.txt"
+          docs-folder: "documentation"
 
       - name: Deploy documents to GH pages
         uses: JamesIves/github-pages-deploy-action@v4
         with:
-          folder: documentation/website/build/html
+          folder: documentation/_build/html
 
 

.github/workflows/build-documentation.yml

@@ -31,6 +31,6 @@ jobs:
 
       - uses: ammaraskar/sphinx-action@master
         with:
-          pre-build-command: "echo furo >> documentation/website/requirements.txt"
-          docs-folder: "documentation/website"
+          pre-build-command: "echo furo >> documentation/requirements.txt"
+          docs-folder: "documentation"
 

documentation/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

documentation/README.rst

@@ -1,63 +1,65 @@
-This is the documentation for Open Dylan.
+This is the Open Dylan website.
 
-It is built using `Sphinx <http://sphinx.pocoo.org>`_. All content is written
-using ReStructured Text with Sphinx extensions.
+It is built using `Sphinx <https://www.sphinx-doc.org/>`_.  All content is
+written using ReStructured Text with Sphinx extensions.
 
 Preparation
 ===========
 
-Before building this documentation, you will need a copy of Sphinx
-installed. The latest versions of Sphinx use Python 3 so we assume Python 3 is
-in use here.  The easiest way to install Sphinx is to get it from the `Python
-Package Index <http://pypi.python.org/pypi/Sphinx>`_ or to use ``pip3``::
+Installing dependencies
+-----------------------
 
-  sudo pip3 install -U Sphinx
+Some system dependencies need to be satisfied first:
 
-On some systems it might be called just ``pip`` even when installing Python 3
-packages.
+- Python 3 and its package manager pip3.
+- Git
+- Make
 
-You also need to have the git submodule for our Sphinx extension populated.  If
-this is not present for you, do this at the top level of the opendylan
-repository::
+On a Debian-derivative, they're quite easy to fetch::
 
-  git submodule update --init --recursive
+    sudo apt install python3 python3-pip git make
 
-Building
-========
+Now you need the Python dependencies. The easiest way to do this is to use
+``pip3``::
 
-Building the documentation is easy on a system with ``make``. For example::
+    sudo pip3 install -U Sphinx furo
 
-  cd library-reference && make html
+You may also need ``python-dateutil``.
 
-On Windows, use ``make.bat`` instead::
+    sudo pip3 install python-dateutil
 
-  make.bat html
+Building
+========
 
-The generated documentation will be in ``build/html``.  Just viewing the HTML
-locally may not correctly load the CSS files.  A workaround is to cd into
-``build/html`` and run a web server.  For example::
+Get the source if you haven't already::
 
-  python3 -m http.server
+    git clone --recursive https://github.com/dylan-lang/opendylan
 
-or::
+Building the website::
 
-  python2 -m SimpleHTTPServer
+    cd opendylan/documentation
+    mkdir -p /tmp/opendylan.org
+    ./update.sh /tmp/opendylan.org      # for testing
+    ./update.sh /var/www/opendylan.org  # for realz
 
-The pages can then be accessed via::
+The generated site will be in ``_build/html`` and then copied to the output
+directory you specified, along with package docs and the DRM files.
 
-  http://localhost:8000/index.html
+If you are tweaking non-package doc pages you can test your changes by running
+``make html`` again, but the output will only be in ``_build/html``. **To build
+the full website you must use ``update.sh``.**
 
-You can build other formats as well. Run ``make`` or ``make.bat`` without
-arguments to see the available formats.
+Test your changes by running a web server::
 
-Note that to build the PDF files with ``make latexpdf`` it may be necessary (at
-least on Debian) to install these packages:
+    python3 -m http.server --directory /tmp/opendylan.org   # or _build/html
 
-*  latexmk
-*  texlive-latex-recommended
-*  texlive-fonts-recommended
-*  texlive-latex-extra
+or you can eat our own Dylan dogfood and run our HTTP server! ::
 
+    git clone --recursive https://github.com/dylan-lang/http
+    cd http
+    make install
+    cd ...back to website dir...
+    http-server --directory /tmp/opendylan.org   # or _build/html
 
 Link Validation
 ---------------
@@ -67,6 +69,20 @@ are valid.  You can run the link checker by::
 
     make linkcheck
 
+Site Maintenance
+================
+
+#. Update the appropriate info on the download page when a new version of Open
+   Dylan is released.
+
+#. The :file:`update-opendylan.org.sh` script is run periodically via a systemd
+   timer to update the documentation in various repositories by essentially
+   doing a git pull and make html.
+
+   Note that the script copies package docs into
+   ``/var/www/opendylan.org/package/`` and copies the DRM to
+   ``/var/www/opendylan.org/books/drm/`` so it assumes there are no top-level
+   URLs starting with ``/books/drm`` or ``/package``.
 
 Section Header Markup
 =====================