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.
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`.
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
Markdown notation
* [Title1](doc1.md)
* [Title2](doc2.md)
Markdown notation
[API Reference](api_ref.md)
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
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
===== ===== =======
``` ``
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! !!
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.
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.
Template file name | Description |
---|---|
conf.py_t | conf.py template |
Makefile.new_t | Simple Makefile template |
Makefinle_t | Makefile template |
make.bat.new_t | Simple version make.bat template |
make.bat_t | make.bat template |
master_doc.rst_t | First generated.rst template |
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())
Not being able to use templates in conf.py
is too inconvenient to rewrite the source.
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.
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.
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.
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
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
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.
Font Awesome enhances the expressiveness of documents with various font icons. Qiita also supports Font Awesome.
To use Font Awesome with Sphinx, use sphinx_fontawesome, installation is easy with pip
as usual.
pip install sphinx_fontawesome
Edit conf.py
.
import sphinx_fontawesome
extensions = ['sphinx_fontawesome']
If you want to use it from markdown, type HTML normally.
<i class="fa fa-exclamation-triangle" aria-hidden="true"></i>
You can use Font Awesome from Sphinx markdown like this.
Please refer to the Readme of sphinx_fontawesome for how to use from reStructuredText
.
For those who want to work hard with reStructuredText
, there is a plugin in Atom to preview reStructuredText
.
rst-preview: https://atom.io/packages/rst-preview
You can see the preview with ctrl-shift-r
, it uses pandoc
, so please install it first.
Sphinx has some inconveniences in many places, but it can be quite convenient once the environment is in place.
--You can write a document with Markdown
――In case of emergency, you can also write reStructuredText
together.
--You can also import Jupyter notebooks
--It also does an automatic build
--Abundant expansion
--High affinity with Python
--Document generation is also done with a script
I think we are approaching the strongest document environment.
~~ Finally, rewrite conf.py
with the template function Source modification at your own risk, or wait for Sphinx version 1.5.3. ~~
Templates have been fixed in the latest version of Sphinx 1.5.3.
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.
Recommended Posts