jkris/docker-sphinx repository overview

⁠Docker Sphinx

Docker image for Sphinx⁠. Cheatsheet for reStructuredText can be found here⁠

This image contains:

• Sphinx⁠
• A theme:
  • sphinx_rtd_theme⁠
• A variety of plugins:
  • sphinxcontrib-plantuml⁠
  • sphinxcontrib-httpdomain⁠
• Confluence Publisher⁠

⁠Build

git clone [email protected]:jimmikristensen/docker-sphinx.git
cd docker-sphinx
docker build --force-rm -t jkris/docker-sphinx .

⁠Install

docker pull jkris/docker-sphinx

⁠Usage

Besides the regular use os Sphinx described in the section Basic Usage⁠, this project contains three python scripts to make the automation process easier for use in a deployment pipeline.

⁠sphinx_init.py

This script will run the sphinx-quickstart with the arguments necessary for setting up the sphinx project in quiet mode. If run multiple times, it will cleanup before running again. It modifies the conf.py used by sphinx to use environment variables instead of configured values, which enables you to set (and change) the values when the container is started. It will also add any .rst files you have in your directory to the master document (usually index.rst).

⁠sphinx_make.py

This script has two purposes: 1) To copy any images that are stored in assets/images directory into the sphinx build directory and change the path for the image in the generated document, and 2) to run the sphinx make command.

⁠sphinx_confluence_publish.py

This script generates the config.yml file based on the environemtn variables you pass to it and the .rst documents in your directory. If you are using plantuml in your documents or have images or downloads in your sphinx project, these files will be added to the config.yml and attached the confluence page. Furthermore, the plantuml and images referenced in your .rst documents will be converted to confluence image references to the attachments, which means that they will be visible in confluence.

⁠Example

An example of how to use this project is located in the examples dir. This dir contains:

• A sphinx.env file containing the variables used by the python scripts described above in order to 1) initialize a new sphinx project, 2) run the sphinx make commands and 3) push the changes to confluence. An explanation of the different variables can be found in the table under the Sphinx Environment Variables.
• A docs dir containing all the reStructuredText (.rst) files - this is where your source documentation goes.
• A docker-compose.yml file to make it easier to run commands for generating documentation.

From inside the examples dir, run the following docker-compose commands:

⁠Initialization

docker-compose run --rm sphinx python /scripts/sphinx_init.py

This will initialize a new sphinx project creating a sphinxdoc dir containing 1) a source dir with your rst files, 2) an empty build dir, and 3) the sphinx make files. Your source rst files are now ready to be converted into the format you wish.

⁠Make

docker-compose run --rm sphinx python /scripts/sphinx_make.py html

This command will generate HTML files based on the rst files in the source dir. The build/html dir will now contain a .html file for each of your source rst files, including an index.html. In this case several html files will be generated explaining what sphinx is together with some examples of the reStructuredText syntax and PlantUML.

To generate json instead, run the following command:

docker-compose run --rm sphinx python /scripts/sphinx_make.py json

To get a list of conversion options, run the command without arguments:

docker-compose run --rm sphinx python /scripts/sphinx_make.py

⁠Confluence Publish

docker-compose run --rm sphinx python /scripts/sphinx_confluence_publish.py

A precondition for running this command is that you have generated json files beforehand. The command will read the json files and publish the documents specified by the confluencePages variable to the confluence URL given by the confluenceUrl variable using the authentication given by confluenceAuth.

⁠Sphinx Environment Variables (sphinx.env)

⁠Basic Usage

This project can also be used without the python helper scripts simply by invoking the sphinx commands directly.

docker run --rm -i -t -v "${PWD}:/doc" -u "$(id -u):$(id -g)" jkris/docker-sphinx <cmd>

The volume mount ${PWD} should point to the dir containing the .rst files. You can execute any commands within the docker container - read on to see some examples.

⁠Docker Compose

It is recommended to use Docker Compose⁠. An example docker-compose.yml is seen as:

version: "2"
services:
  sphinx:
    image: "jkris/docker-sphinx"
    volumes:
      - "${PWD}:/doc"
    user: "1000:1000"

Now you can run:

docker-compose run --rm sphinx <cmd>

Basic examples using docker-compose:

# create a new sphinx documentation project structure
docker-compose run --rm sphinx sphinx-quickstart
# or using the quiet flag (without interactive wizard)
docker-compose run --rm sphinx sphinx-quickstart  -p 'Project' -a 'Author' --sep --dot=. -v 1.0 --suffix=.rst --master=index --extensions=sphinxcontrib.plantuml --quiet /doc

To see the full list of arguments of the quickstart command, see Invocation of sphinx-quickstart⁠.

After the documentation structure has been setup, you can generate documentation in different formats.

# to generate html
docker-compose run --rm sphinx make html
# to generate json (will be used later in this readme to push to confluence)
docker-compose run --rm sphinx make json

This image contains the sphinx-confluence which means it can be used for pushing documentation to a confluence server. Before this can be done, you need to create a config.yml containing confluence specific information. Read more about confluence-publisher⁠. An example could look like this:

docker-compose run --rm sphinx conf_publisher config.yml --verbose --url <confluence url>/wiki --auth <confluence auth> --force)