I wanted to skip certain extensions when building Sphinx documentation

Premise

I am a person who writes Reveal.js slides in Sphinx based on my own sphinx-revealjs.

Until you use extensions with Sphinx

When writing the source of the slide with the combination of Sphinx + Revealjs, there is such a scene.

presentation.rst


Ansible movement(contents)
-------------------

.. 60sec

.. todo::Playbook of the above demo

Inventory file

*Define a list of servers to execute processing and simple information

The todo directive used here allows you to display todo as in Sphinx. This is useful for making notes such as "what to write after this" or "what you wanted to write".

So, since it is not a built-in extension, it is necessary to specify it as an extension in conf.py used when building with sphinx, but ...

conf.py


extensions = [
    'sphinx.ext.todo',
    'sphinx_revealjs',
]

Build with custom builder fails

When I run it, I get an error like this and the build fails.

$ pipenv run make revealjs
Exception occured
  File "/home/attakei/.local/share/virtualenvs/slides-P9x2JL-m/lib/python3.7/site-packages/sphinx/writers/html5.py", line 885, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: todo_node

Well, I get this error even though the Sphinx extension should be registered properly. When I set the builder to html, the build seems to complete normally. That seems to be due to the own revealjs builder

Track errors ... again this time

Split the extension call from the conf.py side

The library modification smells a lot, so for the time being, play with conf.py.

** "If you specify revealjs as the builder, do not register sphinx.ext.todo in the extension" **

To the goal.

conf.py


extensions = [
    'sphinx_revealjs',
]

if is_not_builder_revealjs:
    extensions += [
       'sphinx.ext.todo',
    ]

Like this

Roughly confirm the builder at the time of conf.py (under limited conditions)

Sphinx recommends a make-based build,

%: Makefile
	@$(SPHINXBUILD) -b $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

In this way, the sphinx-build command is passed. And thankfully, the sphinx.cmd.build module, which is the source of the command, seems to use it on the command line after generating an argument parser separately with a function.

https://github.com/sphinx-doc/sphinx/blob/master/sphinx/cmd/build.py#L97

It feels like a rough look, and it seems that it can be used as it is, so I will plunge into conf.py.

conf.py


import sys
from sphinx.cmd.build import get_parser


sphinx_args = get_parser().parse_args(sys.argv[1:])

extensions = [
    'sphinx_revealjs',
]

if sphinx_args.builder != 'revealjs':
    extensions += [
        'sphinx.ext.todo',
    ]

Now this. When you build, ...

$ pipenv run make revealjs



Copying static files... ...Done
copying extra files...Done
dumping search index in Japanese (code: ja)...Done
dumping object inventory...Done
build success, 3 warnings.

Successful: +1:

Recommended Posts

I wanted to skip certain extensions when building Sphinx documentation
When you want to keep the Sphinx documentation theme as usual
What I did when I wanted to make Python faster -Numba edition-
[Django] I wanted to test when POSTing a large file [TDD]
Wercker step to compile Sphinx documentation
Hash chain I wanted to avoid (2)
I wanted to evolve cGAN to ACGAN
Hash chain I wanted to avoid (1)
When introducing the Google Cloud Vision API to rails, I followed the documentation.
What I referred to when studying tkinter
I wanted to solve ABC160 with Python
I wanted to solve ABC159 in Python
I wanted to solve ABC172 with Python
I really wanted to copy with selenium
Implemented DQN in TensorFlow (I wanted to ...)