Add chapters to the docs navigation, allow building docs in docker. (#954)

We have lots of documentation and the main navigation is crowded, so split
it in several chapters with clear names.

Also, allow to build (and serve) the docs from a docker image to make it
easy for contributors to check their work. This also makes it possible to
build the docs in the CI.

Author: DimCitus

.dockerignore

@@ -1,8 +1,14 @@
 .git
 src/bin/pg_autoctl/pg_autoctl
-docs
 Dockerfile
 
+docs/tutorial/monitor
+docs/tutorial/node1
+docs/tutorial/node2
+docs/tikz/*svg
+docs/tikz/*pdf
+docs/tikz/*png
+
 # Global excludes across all subdirectories
 *.o
 *.bc

.github/workflows/run-tests.yml

@@ -36,7 +36,7 @@ jobs:
             TEST: linting
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: Set environment variables
         run: |
@@ -62,6 +62,11 @@ jobs:
         run: |
           make lint
 
+      - name: Build documentation
+        if: ${{ env.TEST == 'linting' }}
+        run: |
+          make build-docs
+
       - name: Build Docker Test Image
         if: ${{ env.TEST != 'linting' }}
         run: |

Dockerfile.docs

@@ -0,0 +1,43 @@
+FROM debian:bullseye-slim
+
+RUN apt-get update \
+  && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+	curl \
+	git \
+	gawk \
+	make \
+	python3 \
+    python3-sphinx \
+    python3-pip \
+	sudo \
+	texlive \
+    texlive-luatex \
+	texlive-latex-extra \
+    texlive-fonts-extra \
+	latexmk \
+	poppler-utils \
+	&& rm -rf /var/lib/apt/lists/*
+
+RUN pip3 install sphinx_rtd_theme
+
+WORKDIR /usr/src/pg_auto_failover
+
+COPY Makefile ./
+COPY ./src ./src
+COPY ./docs ./docs
+
+# avoid building the main binary to generate the FSM graphics
+RUN touch docs/fsm.png
+RUN touch src/bin/pg_autoctl/git-version.h
+
+# still make sure we can produce the tikz graphics (pdf, svg)
+# use TERM=dumb to avoid tput error messages when we don't have a terminal
+RUN make TERM=dumb -C docs/tikz clean all
+
+# and finally use python-sphinx to produce the docs in html
+RUN make -C docs html
+
+RUN find docs
+
+EXPOSE 8000/tcp
+CMD ["python3", "-m", "http.server", "--directory", "docs/_build/html"]

Makefile

@@ -20,6 +20,9 @@ BUILD_CONTAINER_NAME = pg_auto_failover_build
 TEST_CONTAINER_NAME = pg_auto_failover_test
 DOCKER_RUN_OPTS = --privileged --rm
 
+# make serve-docs uses this port on localhost to expose the web server
+DOCS_PORT = 8000
+
 PGVERSION ?= 14
 
 BUILD_ARGS_PG11 = --build-arg PGVERSION=11 --build-arg CITUSTAG=v9.5.10
@@ -243,6 +246,12 @@ spellcheck:
 docs: $(FSM) tikz
 	$(MAKE) -C docs html
 
+build-docs:
+	docker build -t pg_auto_failover:docs -f Dockerfile.docs .
+
+serve-docs: build-docs
+	docker run --rm -it -p $(DOCS_PORT):8000 pg_auto_failover:docs
+
 tikz:
 	$(MAKE) -C docs/tikz all
 

docs/citus-quickstart.rst

@@ -1,7 +1,7 @@
 .. _citus_quickstart:
 
-Citus Cluster Quick Start
-=========================
+Citus Tutorial
+==============
 
 In this guide we’ll create a Citus cluster with a coordinator node and three
 workers. Every node will have a secondary for failover. We’ll simulate

docs/how-to.rst

@@ -1,7 +1,7 @@
 .. _how-to:
 
-Main pg_autoctl commands
-========================
+Quick Start
+===========
 
 pg_auto_failover includes the command line tool ``pg_autoctl`` that
 implements many commands to manage your Postgres nodes. To implement the
@@ -19,7 +19,9 @@ To understand which replication settings to use in your case, see
 
 To follow a step by step guide that you can reproduce on your own Azure
 subscription and create a production Postgres setup from VMs, see the
-:ref:`tutorial` section.
+:ref:`azure_tutorial` section. To get started with a local setup using
+docker-compose to run multiple Postgres nodes, see the :ref:`tutorial`
+section.
 
 To understand how to setup pg_auto_failover in a way that is compliant with
 your internal security guide lines, read the :ref:`security` section.

docs/index.rst

@@ -37,23 +37,43 @@ __ https://github.com/citusdata
    level of free guidance.
 
 .. toctree::
-   :maxdepth: 4
-   :caption: Contents:
+   :hidden:
+   :caption: Getting Started
 
    intro
    how-to
    tutorial
    azure-tutorial
+   install
+
+.. toctree::
+   :hidden:
+   :caption: Architecture
+
    architecture
    architecture-multi-standby
-   citus
-   citus-quickstart
    failover-state-machine
    fault-tolerance
-   install
    security
+
+.. toctree::
+   :hidden:
+   :caption: Citus
+
+   citus
+   citus-quickstart
+
+.. toctree::
+   :hidden:
+   :caption: Manual Pages
+
    ref/manual
    ref/configuration
+
+.. toctree::
+   :hidden:
+   :caption: Operations
+
    operations
    faq
 

docs/tutorial.rst

@@ -1,7 +1,7 @@
 .. _tutorial:
 
-pg_auto_failover Tutorial
-=========================
+Tutorial
+========
 
 In this guide we’ll create a Postgres setup with two nodes, a primary and a
 standby. Then we'll add a second standby node. We’ll simulate failure in the