Using sphinx to deploy a documentation site¶

Why Sphinx?¶

First of all I needed to find a tool which match my constraints releaved in my mockup. For this purpose I found a gorgeous website which cover the topic of documentation solutions.

The main idea was simply to recreate a GitBook-like website for my documentation this year as a new challenge from past year.

To match all my requirements, there was nearly one only solutions and it was Sphinx!

Sphinx has the hability to handle multiple languages by it’s Internalization method. This is particularly important here in Switzerland cause we have 4 national languages (German, French, Italian, Romansh).

The other part is that I wanted to handle easily pdf, epub, etc. directly during the build of my website to do an usable book to be used neared the machines. And Sphinx handle that quiet beautifully.

Here the expected results:

Markdown or reStructuredText (reST)?¶

Both of them if you only use the extension .md! More details here: http://fab.academany.org/2018/labs/fablabat3flo/students/mat-bgn/wiki/mdrest.html

How to start?¶

The only ones files that you need are those:

Makefile
.gitlab-ci.yml
conf.py

The other part that you need for working trough your wiki built-in project you will use Submodule, see below.

Makefile¶

You can get the Makefile here :

https://gitlab.fabcloud.org/academany/fabacademy/2018/labs/fablabat3flo/students/mat-bgn/raw/master/Makefile

No worry about it we won’t waste time, simply copy it to your main project aside your default README.md. The magical trick here is simply to talk to the right output flow while build is called.

.gitlab-ci.yml¶

Here is the Continuous Integration file for GitLab with extensions like Image responsive. Don’t change it either you know what you are doing. Of course you can either remove the website (pages) compilation or the pdf (compile_pdf) part if don’t need it.

pages:
  script:
  - apk --no-cache add py-pip python-dev git make
  - pip install sphinx guzzle_sphinx_theme recommonmark markdown m2r
  - git clone https://github.com/Blendify/sphinx-bootstrap-directives.git
  - cd sphinx-bootstrap-directives
  - python setup.py build
  - python setup.py install
  - cd docs
  - rm -Rf source
  - cd ../..
  - make html
  - mv _build/html/ public/
  artifacts:
    paths:
    - public
  only:
  - master

compile_pdf:
  image: aergus/latex
  script:
    - wget -L https://bootstrap.pypa.io/get-pip.py
    - python get-pip.py
    - pip install sphinx guzzle_sphinx_theme recommonmark markdown m2r
    - make latex
    - make latexpdf
    - mv _build/latex/FabAcademy2018.pdf FabAcademy2018.pdf
  artifacts:
    paths:
    - FabAcademy2018.pdf
  only:
    - master

conf.py¶

Here you can adapt all the settings regarding your own project. It’s also the file where we import the extensions like: Image responsive

import sys, os, subprocess

from sphinx.highlighting import lexers
from pygments.lexers.web import PhpLexer
from recommonmark.transform import AutoStructify
from recommonmark.parser import CommonMarkParser

sys.path.insert(0, os.path.abspath(os.path.join('../..', 'sphinx-bootstrap-directives')))

# -----------------------------------------------------------------------------
# GENERAL CONFIGURATION
# -----------------------------------------------------------------------------

project = u'Fab Academy 2018'
copyright = u'2018, Matthieu Borgognon'
authors = u"Matthieu Borgognon"
master_doc = 'index'
templates_path = ['_templates']
extensions = [
     'm2r',]
source_suffix = ['.rst', '.md']
version = '0.1.0'
exclude_patterns = ['_build']
github_doc_root = 'http://fab.academany.org/2018/labs/fablabat3flo/students/mat-bgn/'


# -----------------------------------------------------------------------------
# HTML THEMES SETTINGS
# -----------------------------------------------------------------------------

html_show_sourcelink = False
html_sidebars = {
    '**': ['logo-text.html',
           'globaltoc.html',
           'localtoc.html',
           'searchbox.html']
}

import guzzle_sphinx_theme

extensions.append("guzzle_sphinx_theme")
html_theme_path = guzzle_sphinx_theme.html_theme_path()
html_theme = 'guzzle_sphinx_theme'

# Guzzle theme options (see theme.conf for more information)
html_theme_options = {
    "base_url": "http://fab.academany.org/2018/labs/fablabat3flo/students/mat-bgn/"
}

# ------------------------------------------------------------------------------
# OPTIONS FOR: LATEX OUTPUT
# ------------------------------------------------------------------------------
latex_elements = {
    # The paper size ("letterpaper" or "a4paper").
    "papersize": "a4paper",

    # The font size ("10pt", "11pt" or "12pt").
    # "pointsize": "10pt",

    # Additional stuff for the LaTeX preamble.
    # "preamble": "",
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
  ("index", "FabAcademy2018.tex", u"Fab Academy 2018", authors, "manual"),
]

# latex_logo = None

def setup(app):
    app.add_config_value('recommonmark_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)

Using the wiki for editing¶

Submodule

First create a file called .gitmodules and put those lines in it depending your relative project path:

[submodule "wiki"]
    path = wiki
    url = https://gitlab.fabcloud.org/academany/fabacademy/2018/labs/fablabat3flo/students/mat-bgn.wiki.git

Simply add the following code both to the pages script and the compile_pdf script:

- git submodule update --init
- cd wiki
- git checkout master
- git pull
- cd ..

Also check it out¶

Have the JS Power in your Sphinx instance:

Add GANTT capability:

https://mermaidjs.github.io/

Table Of Contents

Contents