All Sphinx Directives

Sphinx comes with a huge number of directives. Some are inherited from RST, others come from the many extensions that are available. But the is no list of all, or the most used directives in Sphinx.

Until now …

Updated on 2018/05/13

Added more opensource projects as a reference to show “all” Directives.

The most used directives to document Sphinx itself

With a simple iPython-script, I counted all directives in all (.rst & .py) files of Sphinx-doc (the latest version, on May 10, 2018); 1758 in total. The table below shows them all, sorted in most-used-order. As you can see many directives are only used once (0.06%) or twice …

Directive	%	Directive	%	Directive	%	Directive	%
versionadded	17.35%	event	1.14%	moduleauthor	0.28%	attention	0.11%
confval	14.39%	autofunction	1.14%	digraph	0.28%	object	0.11%
versionchanged	6.88%	math	1.14%	autoexception	0.28%	todolist	0.11%
automethod	4.89%	image	1.08%	important	0.28%	cmdoption	0.11%
option	4.32%	figure	1.08%	contents	0.23%	tabularcolumns	0.11%
autoattribute	4.10%	index	1.08%	include	0.23%	directivename	0.06%
toctree	3.53%	function	1.02%	glossary	0.23%	testsetup	0.06%
note	2.90%	autosummary	1.02%	sourcecode	0.23%	graph	0.06%
data	2.84%	seealso	0.91%	graphviz	0.23%	sidebar	0.06%
autoclass	2.84%	warning	0.91%	ifconfig	0.23%	centered	0.06%
module	2.67%	todo	0.74%	cssclass	0.17%	hlist	0.06%
class	1.93%	method	0.74%	autodata	0.17%	sectionauthor	0.06%
attribute	1.93%	automodule	0.68%	doctest	0.17%	productionlist	0.06%
literalinclude	1.65%	describe	0.51%	testcode	0.17%	caution	0.06%
highlight	1.59%	raw	0.46%	testoutput	0.17%	danger	0.06%
only	1.59%	admonition	0.46%	topic	0.11%	error	0.06%
rubric	1.54%	program	0.46%	tip	0.11%	staticmethod	0.06%
deprecated	1.42%	table	0.40%	exception	0.11%	userdesc	0.06%
currentmodule	1.14%	hint	0.34%	envvar	0.11%	meta	0.06%

More directives

As promised, I want to show all directives. That is hardly possibly, as RST (and so, Sphinx) is extendable; anybody can add directives… Still, we can come close, by scanning more documentation-projects.

The same script can scan several (documentation) projects; by summing the resulting DirectiveCounters together, the big-table below is produced.

Currently, I scan some of my personal projects, and a few open-source ones:

• cPython

• Needs (sphinxcontrib)

• Numpy

• Pandas

• pygments

• ReadTheDocs

• Scipy

• Sphinx-doc

Directive	%	Directive	%	Directive	%	Directive	%
versionadded	12.54%	cmdoption	0.41%	program	0.10%	uml	0.02%
method	12.33%	image	0.40%	needfilter	0.10%	testoutput	0.02%
function	8.61%	admonition	0.37%	needtable	0.10%	impl	0.02%
ipython	7.95%	plot	0.36%	raw	0.09%	error	0.01%
versionchanged	6.11%	code	0.35%	testcode	0.09%	update	0.01%
math	5.52%	option	0.34%	role	0.09%	slide	0.01%
data	4.17%	highlightlang	0.33%	event	0.09%	testcleanup	0.01%
attribute	4.15%	autoattribute	0.31%	needlist	0.09%	pygmentsdoc	0.01%
note	3.79%	productionlist	0.30%	tip	0.08%	cssclass	0.01%
index	3.54%	autoclass	0.22%	story	0.07%	autodata	0.01%
class	3.48%	2to3fixer	0.22%	hint	0.07%	danger	0.01%
autosummary	2.83%	tabularcolumns	0.22%	abstractmethod	0.07%	object	0.01%
seealso	2.18%	contents	0.21%	caution	0.05%	nextslide	0.00%
module	1.68%	decorator	0.21%	test	0.05%	epigraph	0.00%
exception	1.12%	figure	0.19%	glossary	0.04%	miscnews	0.00%
warning	1.11%	coroutinemethod	0.19%	topic	0.04%	autoaccessor	0.00%
confval	1.09%	container	0.18%	coroutinefunction	0.04%	autoaccessorattribute	0.00%
toctree	1.08%	highlight	0.18%	important	0.04%	autoaccessorcallable	0.00%
sectionauthor	1.04%	classmethod	0.18%	attention	0.03%	autoaccessormethod	0.00%
deprecated	1.04%	req	0.17%	table	0.03%	_aheui	0.00%
currentmodule	0.95%	spec	0.16%	graphviz	0.03%	directivename	0.00%
doctest	0.79%	only	0.15%	needflow	0.03%	graph	0.00%
include	0.74%	todo	0.15%	ifnotslides	0.02%	centered	0.00%
moduleauthor	0.61%	pdbcommand	0.14%	staticmethod	0.02%	hlist	0.00%
automodule	0.57%	describe	0.14%	ifconfig	0.02%	userdesc	0.00%
rubric	0.53%	envvar	0.14%	digraph	0.02%	meta	0.00%
opcode	0.52%	post	0.12%	autoexception	0.02%	needfiler	0.00%
sourcecode	0.48%	sidebar	0.12%	needimport	0.02%
literalinclude	0.47%	testsetup	0.11%	postlist	0.02%
automethod	0.47%	autofunction	0.11%	todolist	0.02%

Note

Are you missing a directive?

Find a project using it and let me know! And I will rerun the scripts. And simular when a major documentation-project should be included to get better stats.

Remote MD   Compiler Compiler

Comments

comments powered by Disqus