Said thing: I want everyone to use Sphinx conveniently
Sphinx is very convenient, but the documentation process was very cumbersome. Therefore, I made a module "sphinx-quickstart-plus" that extends Sphinx.
https://github.com/pashango2/sphinx-qsp
Easy to install with pip. It depends on the Sphinx module, so please install Sphinx in advance.
$ pip install sphinx-quickstart-plus
Until now, document creation was typed as sphinx-quickstart, but just type sphinx-quickstart-plus.
$ sphinx-quickstart-plus
Then, the following message will be played.
output
Welcome to the Sphinx 1.5.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Enter the root path for documentation.
> Root path for the documentation [.]: document_path
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
...
The output is exactly the same as the previous sphinx-quickstart.
You might think, "Nothing has changed," but please keep in touch.
output
...
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:
> ext_commonmark:use CommonMark and AutoStructify (y/n) [n]: y
> ext_nbshpinx:provides a source parser for *.ipynb files (y/n) [n]: y
> ext_blockdiag:Sphinx extension for embedding blockdiag diagrams (y/n) [n]: y
> ext_fontawesome:use font awesome (y/n) [n]: y
> ext_rtd_theme:use Read the Doc theme (y/n) [n]: y
> ext_autobuild:autobuild: Watch a directory and rebuild the documentation (y/n) [n]: y
Finally, there are questions that weren't in sphinx-quickstart.
The current extensions and descriptions are as follows:
| Extension name | Description |
|---|---|
| ext_commonmark | .rstnot only.md(CommonMark)Will be available |
| ext_nbshpinx | You will be able to import Jupyter Notebook |
| ext_blockdiag | You will be able to draw block diagrams |
| ext_fontawesome | Font Awesome will be available from reST |
| ext_rtd_theme | You will be able to use the Read the Docs theme |
| ext_autobuild | You will be able to use auto build |
These Sphinx extensions will be available without editing conf.py.
Not only that, when you start sphinx-quickstart-plus again, the question at the beginning changes.
output
> Use latest setting? (y/n) [y]: y
If you type'y', just answer the 5 items Path, Project name, ʻAuthor, Version, and Release, and a document with the same settings as the previous document will be created. It remembers the document settings created in the previous sphinx-quickstart-plus`.
By the way, if you type'n', the usual sphinx-quickstart question will be played, but since the default setting is the last setting, it is easy because you can press the ʻEnter` key repeatedly except for the changed part. is.
$ sphinx-quickstart-plus
> Use latest setting? (y/n) [y]: n
...
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [y]: <-The default is the last input
conf.py on each extension selectionext_commonmark
conf.py
# ----- CommonMark
source_suffix = [source_suffix, '.md']
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
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)
ext_nbshpinx
conf.py
# ----- Jupyter Notebook nbsphinx
extensions.append('nbsphinx')
exclude_patterns.append('**.ipynb_checkpoints')
ext_blockdiag
conf.py
# ----- blockdiag settings
extensions.extend([
'sphinxcontrib.blockdiag',
'sphinxcontrib.seqdiag',
'sphinxcontrib.actdiag',
'sphinxcontrib.nwdiag',
'sphinxcontrib.rackdiag',
'sphinxcontrib.packetdiag',
])
blockdiag_html_image_format = 'SVG'
seqdiag_html_image_format = 'SVG'
actdiag_html_image_format = 'SVG'
nwdiag_html_image_format = 'SVG'
rackiag_html_image_format = 'SVG'
packetdiag_html_image_format = 'SVG'
ext_fontawesome
conf.py
# ----- sphinx-fontawesome
import sphinx_fontawesome
extensions.append('sphinx_fontawesome')
ext_rtd_theme
conf.py
# ----- Read the Docs Theme
html_theme = "sphinx_rtd_theme"
ext_autobuild
auto_build does not rewrite conf.py, but rewrites the Makefile.
$ make livehtml
If you type, auto build will start. For Windows people, ʻauto_build.bat` will be generated, so please run it.
$ auto_build.bat
If you edit .md such as PyCharm, a temporary file will be created and it will also be built, so there is also a setting to ignore the build of some temporary files.
"Sphinx-quickstart-plus" is license-free, please feel free to use it. Please understand that we are not responsible for any disadvantages caused by using this module.
https://github.com/pashango2/sphinx-qsp
Also, since my environment is Ubuntu, I haven't been able to test it on Windows and Mac. I think there are bugs. If you have any problems, please let us know in the issues or comments on GitHub.
This module itself is a small module with less than 400 lines including comments, it takes about 6 hours to create, and most of it is debugging work.
However, it fully supports the rich arguments and features of sphinx-quickstart.
The reason why you can do this is because you are using a technology called ** Monkey Patch **.
A monkey patch is a patch that hijacks the behavior of an existing library and dynamically rewrites it. This is a feat that takes advantage of the characteristics of dynamic languages and is a technique that cannot be imitated by compiled languages. [^ 1]
[^ 1]: I did a monkey patch of the compilation language at http://postd.cc/monkey-patching-in-go/, it's a pretty black magic using assembler.
</ i> Supplement
Monkey patches do not rewrite files in existing libraries.
It is a method to dynamically change the operation without changing the file of the existing library.
Installing sphinx-quickstart-plus does not change the behavior of the original Sphinx library at all.
[Monkey Patch Wikipedia](https://ja.wikipedia.org/wiki/%E3%83%A2%E3%83%B3%E3%82%AD%E3%83%BC%E3%83%91%E3 % 83% 83% E3% 83% 81)
sphinx-quickstart is written in a module called sphinx.quickstart.py.
So, normally import sphinx.quickstart, but ʻask_user function will be rewritten by monkey patch, so be sure to use from .. import ask_user` separately so as not to forget the function pointer of the original processing. I'm importing.
from sphinx import quickstart
from sphinx.quickstart import ask_user, generate, do_prompt, nonempty, boolean
Overwrite the quickstart.ask_user function with the monkey_patch_ask_user function and hijack it.
# monkey patch
quickstart.ask_user = monkey_patch_ask_user
After doing its own processing with the monkey_patch_ask_user function, the original quickstart.ask_user function is called.
def monkey_patch_ask_user(d):
...Original processing
#Original ask_user call
ask_user(d)
...Original processing
I've hijacked various other functions with monkey patches, but basically the same thing is done.
Finally, call quickstart.main.
quickstart.main(argv)
Did you want to further expand ‘sphinx-quickstart-plus’? Editing ‘sphinx-quickstart-plus’ source code for extension is not cool. (Would you like to extend'sphinx-quickstart-plus' further? Don't be foolish to edit the code for'sphinx-quickstart-plus' to extend it)
Let’s monkey patch! (Let's do a monkey patch!)
Below is an example of a simple extension. (The code below is an example of a simple extension)
from sphinx_qsp import quickstart_plus
# Setting your extension.
your_extension = quickstart_plus.Extension(
"ext_your_ext", "your extensions description.",
conf_py="""
# ----Your Extension
import your_extension_package
extension.append("your-extension_name")
)
""",
package=["your_extension_packge"]
)
# Add your extension.
quickstart_plus.qsp_extensions.extend([
your_extension
])
# Run sphinx-quickstart-plus.
quickstart_plus.main()
The base class of extension is the following code. (The code of the base class used for extension is as follows)
class Extension(object):
def __init__(self, key, description, conf_py=None, new_makefile=None,
makefile=None, package=None):
self.key = key
self.description = description
self.conf_py = conf_py
self.new_makefile = new_makefile
self.makefile = makefile
self.package = package or []
# noinspection PyUnusedLocal
def extend_conf_py(self, d):
return self.conf_py
def extend_makefile(self, d, make_mode):
return self.new_makefile if make_mode else self.makefile
The extended class of ‘sphinx-autobuild’ is the following code. (The extension class of ‘sphinx-autobuild’ is as follows)
class AutoBuildExtension(Extension):
def extend_makefile(self, d, make_mode):
if d['batchfile']:
batchfile_path = os.path.join(d['path'], 'auto_build.bat')
source_dir = d['sep'] and 'source' or '.'
build_dir = d['sep'] and 'build' or d['dot'] + 'build'
open(batchfile_path, "w").write(
AUTO_BUILD_BATCH.format(
build_dir=build_dir, source_dir=source_dir,
AUTOBUILD_IGNORE=" ".join(AUTOBUILD_IGNORE),
)
)
makefile = self.new_makefile if make_mode else self.makefile
return makefile.format(" ".join(AUTOBUILD_IGNORE))
I personally created some documentation, but it's really useful.