Sphinx

Sphinx venv

Install virtualenv package

> sudo dnf install python3-virtualenv

Create and activate venv

> python3 -m venv sphinx
> source sphinx/bin/activate

Install python package in venv

> pip install --upgrade pip
> pip install Sphinx
> pip install sphinx_rtd_theme
> pip list

Tip

update packages in virtualenv

> pip list --outdated | \
awk 'NR > 2 { print $1 }' | \
xargs pip install -U

Starting Sphinx

Installing your doc directory

You may already have sphinx sphinx installed – you can check by doing:

> python -c 'import sphinx'

If that fails grab the latest version of and install it with:

> sudo easy_install -U Sphinx

Now you are ready to build a template for your docs, using sphinx-quickstart:

> sphinx-quickstart

accepting most of the defaults. I choose “sampledoc” as the name of my project. cd into your new directory and check the contents:

home:~/tmp/sampledoc> ls
Makefile     ../_static              conf.py
_build               _templates      index.rst

The index.rst is the master ReST for your project, but before adding anything, let’s see if we can build some html:

> make html

If you now point your browser to _build/html/index.html, you should see a basic sphinx site.

../_images/basic_screenshot.png

Fetching the data

Now we will start to customize out docs. Grab a couple of files from the web site or git. You will need getting_started.rst and ../_static/basic_screenshot.png. All of the files live in the “completed” version of this tutorial, but since this is a tutorial, we’ll just grab them one at a time, so you can learn what needs to be changed where. Since we have more files to come, I’m going to grab the whole git directory and just copy the files I need over for now. First, I’ll cd up back into the directory containing my project, check out the “finished” product from git, and then copy in just the files I need into my sampledoc directory:

home:~/tmp/sampledoc> pwd
/Users/jdhunter/tmp/sampledoc
home:~/tmp/sampledoc> cd ..
home:~/tmp> git clone https://github.com/matplotlib/sampledoc.git tutorial
Cloning into 'tutorial'...
remote: Counting objects: 87, done.
remote: Compressing objects: 100% (43/43), done.
remote: Total 87 (delta 45), reused 83 (delta 41)
Unpacking objects: 100% (87/87), done.
Checking connectivity... done
home:~/tmp> cp tutorial/getting_started.rst sampledoc/
home:~/tmp> cp tutorial/_static/basic_screenshot.png sampledoc/_static/

The last step is to modify index.rst to include the getting_started.rst file (be careful with the indentation, the “g” in “getting_started” should line up with the ‘:’ in :maxdepth:

Contents:

.. toctree::
   :maxdepth: 2

   getting_started.rst

and then rebuild the docs:

> cd sampledoc
> make html

When you reload the page by refreshing your browser pointing to _build/html/index.html, you should see a link to the “Getting Started” docs, and in there this page with the screenshot. Voila!

Note we used the image directive to include to the screenshot above with:

.. image:: ../_static/basic_screenshot.png

Next we’ll customize the look and feel of our site to give it a logo, some custom css, and update the navigation panels to look more like the sphinx site itself.

Sphinx CI

Configuration

Create .gitlab-ci.yml

---
before_script:
  - date

stages:
  - check
  - build

check:
  stage: check
  script:
    - source $HOME/Venv/sphinx/bin/activate
    - cd $HOME/builds/df953c97/0/guillaume/sphinx/sphinx_guisam/
    - make linkcheck
    - deactivate
  only:
    - master

build:
  stage: build
  script:
    - source $HOME/Venv/sphinx/bin/activate
    - cd $HOME/builds/df953c97/0/guillaume/sphinx/sphinx_guisam/
    - make html
    - sudo rsync -av --chmod=D750,F640 --chown=www-data:www-data --delete \
      $HOME/builds/df953c97/0/guillaume/sphinx/sphinx_guisam/_build/html/ /srv/guisam.xyz/www
    - deactivate
  only:
    - master
  when: on_success
...

Sudoers file

Create /etc/sudoers.d/gitlab-runner

Cmnd_Alias GTR = /usr/bin/rsync -av --chmod=* --chown=* --delete <sphinx_working_dir>/_build/html/ /srv/guisam.xyz/www
gitlab-runner  ALL=NOPASSWD: GTR

Sphinx Docker

Docker file

Dockerfile

FROM alpine:latest
MAINTAINER guisam

ENV REFRESHED_AT 2021-02-13

ENV SRV_DIR=/srv
ENV WORKING_DIR=/srv/sphinx_guisam

COPY ./requirements.pip $SRV_DIR
WORKDIR $WORKING_DIR

RUN mkdir -p ${WORKING_DIR} && \
        apk add py3-pip make && \
        pip list --outdated | \
        awk 'NR > 2 { print $1 }' | \
        xargs pip install -U && \
        pip install -r ${SRV_DIR}/requirements.pip

CMD sphinx-autobuild --host 0.0.0.0 --port 8001 ${WORKING_DIR} ${WORKING_DIR}/_build

requirements.pip

sphinx
sphinx-autobuild
sphinx_rtd_theme
recommonmark
sphinx_copybutton
sphinxcontrib.mermaid

Docker engine

Build image

> docker build --rm -t guisam/sphinx:dev .

Run

> docker run -d --rm --name sphinx -it \
  -v ~/_git/guigit/sphinx/sphinx_guisam:/srv/sphinx_guisam:Z \
  -p 8080:8001 guisam/sphinx:dev

Display console

> docker logs sphinx -f
+--------------------------------- manual build ---------------------------------
| Running Sphinx v3.4.3
| loading pickled environment... done
| building [mo]: targets for 0 po files that are out of date
| building [html]: targets for 0 source files that are out of date
| updating environment: 0 added, 0 changed, 0 removed
| looking for now-outdated files... none found
| no targets are out of date.
| build succeeded.
|
| The HTML pages are in _build.
+--------------------------------------------------------------------------------
[I 210120 22:22:07 server:335] Serving on http://0.0.0.0:8001
[I 210120 22:22:07 handlers:62] Start watching changes
[I 210120 22:22:07 handlers:64] Start detecting changes
[I 210120 22:22:20 handlers:135] Browser Connected: http://localhost:8080/system/sphinx.html
[I 210120 22:22:20 handlers:135] Browser Connected: http://localhost:8080/system/systemd.html

Only generate html

> docker run --rm --name sphinx -it \
  -v ~/_git/guigit/sphinx/sphinx_guisam:/srv/sphinx_guisam:Z \
  -p 8080:8001 guisam/sphinx:dev make html

Docker compose

docker-compose.yml

sphinx:
    build: .
    ports:
        - '8080:8001'
    volumes:
        - '/home/guigui/_git/guigit/sphinx/sphinx_guisam:/srv/sphinx_guisam:Z'
> alias dcs='docker-compose -f ~/_git/guigit/sphinx/docker-compose.yml'
> dcs up -d --build
> dcs ps
> dcs logs -f
> dcs down