[PYTHON] I want Sphinx to be convenient and used by everyone

Sphinx is a very nice document generation tool. I tried to make this great tool popular in the company, but no one uses it.

I looked back at when everyone would give up on Sphinx.

--I don't know or want to remember reStructuredText --Stop because the default theme is hard to see --sphinx-quickstart has too many questions to stop halfway through --I don't use it because it is troublesome to edit conf.py every time I create a document. --Every time I check the document, make html is troublesome, so I will not use it ――Recently, I write documents with Jupyter, so ...

Is it such a place? Perhaps this is the main reason why Sphinx isn't popular.

Use Markdown

Unfortunately, the mainstream markup language is Markdown instead of reStructuredText. I think everyone can use Markdown.

Sphinx will be able to use Markdown with recommonmark. Many people have written articles on how to set recommonmark, please refer to the following articles.

I tried Sphinx with Markdown (Part 2)

recommonmark can be installed with pip.

pip install commonmark recommonmark

Edit conf.py as follows.

conf.py

source_suffix = ['.rst', '.md']

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

It also describes the ʻAutoStructify component that extends the recommonmark`.

AutoStructify component

Once you have set up the ʻAutoStructify component, you will be able to use various extensions of reStructuredText from Markdown. ʻEdit conf.py to enable the AutoStructify component.

conf.py

from recommonmark.transform import AutoStructify

github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
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)

On markdown, you will be able to:

--toctree generation --Links to other documents --Formula / Inline formula [^ 1] --Embedding reStructuredText

[^ 1]: Extensions such as sphinx.ext.mathjax must be enabled to use formulas

toctree generation

Markdown notation

* [Title1](doc1.md)
* [Title2](doc2.md)

Links to other documents

Markdown notation

[API Reference](api_ref.md)

Formula / Inline Formula

Markdown notation

```math
E = m c^2
``` ``

You can also use inline formulas.

Markdown notation

This formula `$ y=\sum_{i=1}^n g(x_i) $`

reference http://recommonmark.readthedocs.io/en/latest/auto_structify.html

Problem that "table structure" of Commonmark cannot be used

It's nice to be able to write markdown with recommonmark, but I can't use a table. This is because CommonMark does not support tables, and it seems unlikely that tables will be supported in the near future.

There was an issue on GitHub of recommonmark, but it says" ʻeval_rst` should I use it?"

https://github.com/rtfd/recommonmark/issues/3

When it comes to table composition, reStructuredText is more expressive, and ʻeval_rst` doesn't break the markdown description, so I think this is fine for the time being.

In ʻeval_rst`, the table structure is as follows.

```eval_rst
=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======
``` ``

Set an easy-to-read theme

For the time being, Markdown and its extensions are now available, so it has become quite convenient. The rest is an easy-to-read theme setting.

I've tried several themes, but I think the Read The Docs Theme is the easiest to read.

You can easily do it with installation pip.

pip install sphinx_rtd_theme

Then edit conf.py.

conf.py

import sphinx_rtd_theme

html_theme = "sphinx_rtd_theme"

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

It's much easier to see! !!

Simplify document generation

The theme has become easier to see, and it has become quite convenient.

By the way, I have set Markdown, set the theme, and edited a fair amount of conf.py. This work ** has to be done every time I create a document **, it's too inconvenient, what's that?

As expected, editing conf.py every time is too painful, let's use the template function.

** Caution ** Currently, to use the conf.py template, edit the Sphinx version (1.5.2) source file. If you do, please do so at your own risk.

Use the template function

sphinx-quickstart has an option called --templatedir. sphinx-quickstart uses jinja2 to generate various files such as conf.py and Makefile from templates.

All you have to do is prepare a template file that uses the conf.py that you messed up with as a template!

The template file template should be in the following location, please read as appropriate for each environment.

Python path /site-packages/Sphinx-x.x.x-pyx.x.egg/sphinx/templates/quickstart

If you cannot find the file, search for the file conf.py_t to find it. Put conf.py_t with recommonmark and rtd_theme on gist.

https://gist.github.com/pashango2/399010efaa546a47db5c82c72e4f3b5e

Place conf.py_t somewhere in a directory of your choice. There are some files in the template directory, but as long as you read the source of sphinx-quickstart, the non-existent template files will look at the system template files, so you don't need to copy all the files.

However, conf.py is not rewritten!

Execute sphinx-quickstart with the directory containing the template file.

sphinx-quickstart --templatedir=my_sphinx_template

However, the conf.py is not rewritten no matter how many times the command is executed. Other files such as Makefile are rewritten, but conf.py is not rewritten, so read the source.

The code looks like this on line 442 of sphinx / quickstart.py.

quickstart.py

    with open(os.path.join(package_dir, 'templates', 'quickstart', 'conf.py_t')) as f:
       conf_text = convert_python_source(f.read())

Only conf.py_t directly specifies the files under the package.

quickstart.py

    # with open(os.path.join(package_dir, 'templates', 'quickstart', 'conf.py_t')) as f:
    conf_path = os.path.join(templatedir, 'conf.py_t') if templatedir else None
    if not conf_path or not path.isfile(conf_path):
        conf_path = os.path.join(package_dir, 'templates', 'quickstart', 'conf.py_t')
    with open(conf_path) as f:
        conf_text = convert_python_source(f.read())

• An error occurred when template_dir is None, we will fix it (2017/02/05)

Not being able to use templates in conf.py is too inconvenient to rewrite the source.

About source rewriting of Sphinx (2017-02-08 postscript)

Currently, it is a bug that the template function does not work for conf.py.

The above changes have been pulled and merged and will be fixed in 1.5.3, which will be released in mid-March. I made a pull request on Github for the first time, but I made a lot of mistakes, and I would like to thank the Sphinx contributors for working with me.

Make sphinx-quickstart convenient

The template matter is a little sloppy, but it's getting more and more convenient as I'm freed from editing conf.py every time. sphinx-quickstart is a problem that is no longer quick as the number of items increases with each version.

sphinx-quickstart has various options, so you can create a batch file with all the options applied, but it is very troublesome because there are many options.

So I'm going to write a Python script that makes the quick start quick.

my-sphinx-quickstart.py

#! codig:utf-8
import sys
from sphinx.quickstart import ask_user, generate, DEFAULT_VALUE

d = DEFAULT_VALUE.copy()

d["path"] = sys.argv[1]
d["project"] = sys.argv[2]
d["author"] = sys.argv[3]

#Fixed setting
d["version"] = "1.0"
d["language"] = "ja"

#Simple Makefile
d["make_mode"] = True

#Extension settings
d["ext_mathjax"] = True

template_dir = "Template path or None"

#Questions if there are missing parameters (not required, if you like)
ask_user(d)

#Document generation
generate(d, templatedir=template_dir)

Please rewrite the contents by yourself. In the above example, if you execute with the project path, project name, and author name as arguments, all the rest will create a document with default settings.

Basically, the document is created by passing the parameter dictionary and template directory to the sphinx.quickstart.generate method. It may be convenient to move the settings to an external file with Json or write a script to set with the GUI.

Sharing this script and template directory internally will allow you to instantly create custom document generation. This must be convenient.

2017-03-06 postscript

I wrote I made "sphinx-quickstart-plus" to make Sphinx documentation convenient, the setting of conf.py in this article is It is an automatically generated tool.

Do an auto build using sphinx-autobuild

This frees you from the hassle of editing sphinx-quickstart and conf.py when creating your documentation. At this point, I think it's pretty convenient.

Every time I update & check the documentation, I have to type make html, but if I use sphinx-autobuild, it will be built automatically.

It can be installed with pip.

pip install sphinx-autobuild

After installation, the following command will start file monitoring and build at the same time as the update.

sphinx-autobuild  <Source directory> <Build artifact output directory>

This command is lengthy and cumbersome to type every time, so it's useful to add the following code to the generated Makefile.

For Makefile

livehtml:
	sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

For New Makefile

livehtml:
	sphinx-autobuild -b html $(SOURCEDIR) $(BUILDDIR)/html

• Please note that an error will occur unless the indent is set to TAB as a Makefile specification.

The following command will start automatic build monitoring.

make livehtml

Access the document at localhost: 8000. By the way, it is convenient to add the respective code to Makefile_t and Makefile.new_t with the template function mentioned earlier.

Put the Makefile_t and Makefile.new_t templates on the gist.

https://gist.github.com/pashango2/399010efaa546a47db5c82c72e4f3b5e

Import Jupyter notebook (Added 2017-02-06)

Recently, I think that the number of people who write documents using Jupyter has increased. There is an extension of Sphinx called nbsphinx that allows you to capture Jupyter notebooks.

Installation is easy with pip.

pip install nbsphinx

Edit conf.py as usual.

conf.py

extensions = [
    'nbsphinx',
    'sphinx.ext.mathjax',
]
exclude_patterns = ['_build', '**.ipynb_checkpoints']

Make sure that the nbsphinx extension and ignore pattern contains **. ipynb_checkpoints.

Then add the notebook to toctree, write the filename with the extension .ipynb removed. Please note that if you do not put the heading (# title) on the first line of the notebook, it will not be recognized.

In the example below, a file called jupyter.ipynb is added as a document.

Welcome to test's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   jupyter

Jupyter notebook has been added! It's also useful to add nbsphinx to the conf.py_t template.

</ i> Use Font Awesome (Added 2017-02-11)

pip install sphinx_fontawesome

import sphinx_fontawesome
extensions = ['sphinx_fontawesome']

<i class="fa fa-exclamation-triangle" aria-hidden="true"></i>