.. post:: 2020-03-02
:category: sphinx
:language: en
Deploying Sphinx Generated Documentation to Github Pages
========================================================
.. sidebar:: Contents
.. contents::
:local:
`Github Pages `__, a hosting service for
static webpages, is free and easy, although run by Microsoft
[#well_theres_marketing]_. Times are changing.
It took me a while to figure out how to use the service properly,
although, retrospectively, it hasn't been so hard. The main points
were,
* Github Pages, by default, *builds* the stuff you push using `Jekyll
`__. I don't use Jekyll; rather I generate my
site locally, and want to upload *generated content only*. This is
the topic of this post.
* The uploaded content is then served as
`https://jfasch.github.io/jfasch-home-pages/
`__. Bending things to
serve it as `https://www.faschingbauer.me
`__ is the topic of a :doc:`companion
post `.
Create "Site Publication Repo"
------------------------------
.. important::
No, we do *not* pollute our `source repo
`__ (I refer to the local
clone as ``jfasch-home``) with binary content, as Github
suggests. Rather, we distinguish *content* (which is handwritten)
from artifacts that are created during the build.
This reminds me of a company I worked for many years ago:
* They had a huge pile of incomprehensible C/C++ code.
* They built all that in the source tree (no, not with `CMake
`__, or `Meson `__,
or `Automake `__ or
anything else that can do out-of-source builds - but with another
huge pile of incomprehensible Doze ``cmd`` code.).
* They committed the build output. **Yes**: every build they made
was a record in their version control system. The same repo that
contained the source.
* **Effect**: developers did not develop most of their time, but
wait for VC operations. Rational Clearcase can be blamed for many
things, but not for that.
* The company does not exist anymore.
*So*, in parallel to the ``jfasch-home`` local copy of `the upstream
Github repo `__, I create
another `Github repo `__
(cloned locally as ``jfasch-home-pages``). The intent is to use the
``jfasch-home-pages/docs/`` subdirectory as a *deployment location*
for the Sphinx-generated output from ``jfasch-home`` - *one
commit/push per deployment*.
Test that, by populating ``jfasch-home-pages`` with dummy HTML
content. Ah, Jekyll: we provide static files which are not source
code, technically, so we do not want Github to build our site with
Jekyll. This is what the ``.nojekyll`` file tells them to - *suppress
build*.
.. code-block:: console
$ mkdir docs/
$ cat < docs/index.html
Dummy
Hmm. Appears to work.