sphinx doc

This documentation is generated with it.

Installation

Install a new directory with sphinx-quickstart, answer all the questions.

sphinx-quickstart
vim source/conf.py

In conf.py, add all extension you might need. Usually the extensions array for me looks something like :

extensions = [
    'sphinx.ext.todo',
    'sphinx.ext.mathjax',
    'sphinx.ext.autodoc',
    'sphinx.ext.ifconfig',
    'sphinx.ext.mathjax',
    'sphinxprettysearchresults',
    'sphinxcontrib.spelling'
]

Now tweak some settings, like for spelling :

# .lst so sphinx won't try to read it
spelling_word_list_filename='spelling_wordlist.lst'
spelling_show_suggestions=True
spelling_lang='nl_NL'

The default for spelling_wordlist is .txt but that is an extension sphinx reads so make it .lst and remove the .txt version to avoid mistakes.

git rm -f source/spelling_wordlist.txt
sudo apt-get install apsell-nl

The second line install the Dutch dictionary if you need it ! Now if you run 'make spelling' you may find an exception occurred :

make spelling
Exception occurred:
File "/home/kees/.local/lib/python2.7/site-packages/sphinxcontrib/spelling/builder.py", line 192, in finish
    logger.warn('Found %d misspelled words' % self.misspelling_count)
AttributeError: 'SphinxLoggerAdapter' object has no attribute 'warn'

A simple solution to this is open the file mentioned, and change 'warn' on line 192 into 'warning'.

To get the nice read-the-docs layout, you have to changes the theme :

html_theme = 'sphinx_rtd_theme'
html_theme_path = [ '_themes' ]

Warning Note that sphinx 1.5.1 has a bug and 'make html' won't create a correct search index, do: | sudo pip install sphinx==1.5.2 | additional : 1.6.5 is working also !

Another thing when you have a missing search result is to clear the cache !!, hit CTRL-R repeatedly .. mostly the search results will appear.

If you really need to debug the searchindex, the data structure generated is in build/html/searchindex.js : search on the search term with ? because they are in the bottom of the file.

The menu that is generated at the left sidebar is sensitive to where you place it in the text. To make it somewhat clearer you can add :numbered: to the toctree section like this :

.. toctree::
:maxdepth: 10
:hidden:

klopt/index
programming/index

The numbering will make clear at what depth and under which sub-item the menu is placed. Put numbered in the topmost menu to do the complete tree.

PyEnchant

For the spelling check, pyenchant is used, so that needs to be installed as well :

apt-get install python-enchant python-sphinxcontrib.spelling

sphinxprettysearchresults

Also the search index generated by sphinx is horrible looking, all markup is still in the result. To get somewhat better results, install this package.

sudo pip install sphinxprettysearchresults

RestructuredText

This is the new weapon of choice when creating plaintext documents to markup later.

For a good explanation of RestructuredText go to one of these links : * docutils, sphinx again. And for some cheatsheets , also sphinx

Pandoc

Since my previous documentation was done with markdown, most of the pages had to be converted. And this tool does the trick neatly. I will just show the commandline's used most often (-f from, -t to)

pandoc doc.html -f markdown -t rst -o doc.rst

Mostly you want this one if you have xml/html snippets in your text. And since a good part of the documents where still real html :

pandoc doc.html -f html -t rst -o doc.rst

Pandoc tends to turn xml into Sections like this :

.. code-block:: html

[visit](pre)
    content
[visit](/pre)

You can use code or code-block, there seems to be no difference. Also if you doubt if the code is supported: you get a Pygments lexer error if it is not supported.

But that does not seem to render ok, what does looks best is this :

::
    [visit](pre)
        content
    [visit](/pre)

As a guideline: if vim displays it correctly (so the * s do not mess up the highlighting) you are going good.

Conventions

Language

Note Language is English

Warning What the note says, .. English

Dus dit mag niet !!.

::: {.sidebar subtitle="with a subtitle"} This is a sidebar: with a subtitle

As you see i just put in some possible elements here, and the normal text will flow left of this sidebar. :::

Headings

With RestructuredText, you can mark chapter captions with a lot of characters , but the recommended ones are: = - ` : . ~ ^ _ * + # I would like to propose using

• === for heading 1
• --- for heading 2
• ~~~ for heading 3
• ^^^ for heading 4, so please avoid that by splitting docs

I chose === --- and ... first, because these become less prominent, but it turns out the pandoc tool (see above) uses the ones listed above. So, to not mix up things i adopted that, also heading 4 is the butt-ugly ^^^^ so that will probably urge me to split up a file when i need that. :)

Math

You need a math extension for this, i chose for mathjax, the following string :

_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ) 

Will render like this :

\[_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)\]

Spelling check

Use vi spelling check as an alternative.

Before continuing the spell checking chapter note that i currently don't use the spelling plugin but vim spellchecking.

There is a spelling checker installed. You should run

make spelling

And fix the problems... Before doing a :

make clean
make html

the make clean is not needed in theory but all too often i found that the search indices are incomplete when you only do make html !

All documents will be rechecked and you can add unknown words to the file source\spelling_wordlist.lst but try to split words like commandline into command line because that has more change of passing. (yes... i added commandline already.. sigh!)

Customize the theme

This can be done much easier !! visit

So adding this section would change the color without all the fuss below.

html_theme_options = {
    'canonical_url': '',
    'analytics_id': 'UA-XXXXXXX-1',  #  Provided by Google in your dashboard
    'logo_only': False,
    'display_version': True,
    'prev_next_buttons_location': 'bottom',
    'style_external_links': False,
    'style_nav_header_background': '#b9936c',
    # Toc options
    'collapse_navigation': True,
    'sticky_navigation': True,
    'navigation_depth': 4,
    'includehidden': True,
    'titles_only': False
}

I do not know what the other options do, but i am now trying it out to see.

To change the width is not a custom option, but it can be done by including custom css into the sphinx project. So this is not a rtd-theme solution but a sphinx-doc solution.

We did find out what the class of the part is that has to be widened so make a file called source/_static/css/custom.css containing this :

.wy-nav-content { max-width: 100%; }

To include it into the project, you have to make a function called setup in source/conf.py. I placed it as the last statement in the file :

def setup(app):
    app.add_stylesheet('css/custom.css')

Now remake the project with an extra clean. If you changed the content of custom.css the old content seems to linger if you don't do clean.

make clean 
make html

Look in the build directory to see if it was included and contains the correct lines. Then refresh and see if it worked.

ls build/html/_static/css
badge_only.css  custom.css  theme.css

obsolete

The rest of this chapter might com in handy anyway.

This is a quick guide to how i changed it, mostly the commands. It uses sass, and therefore a lot of extra software has to be installed. First ruby, nodejs, and some things as root :

su
apt install ruby
gem install sass
sudo curl https://deb.nodesource.com/setup_6.x > setup.sh
bash setup.sh 
apt-get install -y nodejs

But beware that these have to be installed in the local directory for the sphinx_rtd_theme. If not you will get an error like this :

Fatal error: Unable to find local grunt.

cd ~/projects/doc/sphinx_rtd_theme
npm install grunt
npm install grunt-cli
npm install bower
npm install

That last on is not superfluous, it does a LOT. Now you can alter the sass file, in my case i wanted the width of the screen to change to maximum instead of 800px. Also i wanted to change the main color so i can see which site i am on.

vi sass/_theme_layout.sass

The width is found in :

.wy-nav-content
  padding: $gutter $gutter * 2
  height: 100%
  max-width: 800px
  margin: auto

So alter the width to 100% and run grunt. It will start up a demo interface on which you can see the changes directly, but also after compiling they will be changed in the sphinx documentation as well.

grunt

Now for the color somewhat more is needed, you can alter the setting for the part that's always in view and the setting is in sass/_theme_variables.sass

$nav-search-background-color:         $red

$red is a defined color, and these come from the file : ../bower_components/wyrm/sass/wyrm_core/_wy_variables.sass However if you just define your own color myred in _wy_variables.sass they can be used as well :

$myred:                               #833
$nav-search-background-color:         $red

If all goes well the width is now the total width of the screen.

troubleshooting

sphinxdoc prints all important admonitions to stdout

Install an older version than v2.3 The default on buster (v1.8.4) works but might complain about some extension needing at least v2.1.0 : install that and it will also work.

Do NOT install v2.0.0 because search does not work in combination with sphinx_rtd_theme !!

pip3 install sphinx==2.0.0

sphinx_rtd_theme : {{ super() }} RemovedInSphinx30Warning

This has reportedly been fixed but it is not in the current version, so install sphinx_rtd_theme from git like this :

pip install -e git+https://github.com/readthedocs/sphinx_rtd_theme.git@2b8717a3647cc650625c566259e00305f7fb60aa#egg=sphinx_rtd_theme