-
Notifications
You must be signed in to change notification settings - Fork 1
/
03-08-Sphinx.Rmd
128 lines (104 loc) · 7.09 KB
/
03-08-Sphinx.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
## Sphinx
Sphinx is a documentation generator written in Python by the Python community and initially focused on documenting
Python projects.
It converts reStructuredText files into HTML websites and other formats, such as PDF (through LaTeX), EPUB, texinfo and
man.
Nonetheless, other markup languages (say Markdown) are supported through *extensions*.
Sphinx uses Jinja for HTML templating, which is a text-based engine, inspired by Django templates.
Yet, "*the latex builder does not benefit from prepared themes*" [@sphinx-latex].
A limited interface is provided for customization of some LaTeX options and elements, but the template is fixed.
<aside>
**W** [Sphinx (documentation generator)](https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)), [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText)
- [sphinx-doc.org](https://www.sphinx-doc.org) ([sphinx-doc/sphinx](https://github.com/sphinx-doc/sphinx))
- [jinja.palletsprojects.com](https://jinja.palletsprojects.com/)
- [djangoproject.com](https://www.djangoproject.com/)
</aside>
### Interesting features
The main advantage of Sphinx is powerful cross-reference support.
Unlike Markdown, reStructuredText supports importing/including other sources and referencing the headers across them.
Moreover, `sphinx.ext.intersphinx` allows referencing headers/sections in other independently built and published
projects, by preserving the same syntax used for internal references.
Overall, it is a great fit for distributed ecosystems.
<aside>
- [sphinx-doc.org: Link to other projects’ documentation](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html)
</aside>
Moreover, it supports writing specific blocks of source for some output format only, thus allowing next to each other
description of different visualizations of the same data/info.
It is written in Python and was born in the Python community. Due to the momentum of the Python language in several
areas, Sphinx is probably the most used static site generator. [Read The Docs](https://readthedocs.org/) is a hosted
service based on Sphinx, which provides integration with GitHub and other forge services; it is the documentation
solution used by thousands of projects. Furthermore, Sphinx is used for documenting the Linux Kernel
(see [lwn.net/Articles/692704](https://lwn.net/Articles/692704/)). As a result, there are dozens of [extensions](https://www.sphinx-doc.org/en/master/usage/extensions/index.html)
for all kinds of integrations.
Sphinx is the most used documentation generation tool in the open source EDA tooling ecosystem.
The following sites are based on Sphinx:
- [boolector.github.io](https://boolector.github.io)
- [docs.cocotb.org](https://docs.cocotb.org)
- [docs.verilogtorouting.org](https://docs.verilogtorouting.org)
- [EDAA-org.github.io](https://edaa-org.github.io/)
- [Edalize.rtfd.io](https://edalize.rtfd.io)
- [FuseSoC.rtfd.io](https://fusesoc.rtfd.io)
- [ghdl.github.io/ghdl](https://ghdl.github.io/ghdl)
- [ghdl.github.io/ghdl-cosim](https://ghdl.github.io/ghdl-cosim)
- [IEEE-P1076.gitlab.io](https://ieee-p1076.gitlab.io)
- [im-tomu.github.io/fomu-workshop](https://im-tomu.github.io/fomu-workshop)
- [juanmard.github.io/icestudio](https://juanmard.github.io/icestudio)
- [pydoit.org/contents](https://pydoit.org/contents.html)
- [pyVHDLParser.rtfd.io](https://pyvhdlparser.rtfd.io)
- [SpinalHDL.github.io/SpinalDoc-RTD](https://spinalhdl.github.io/SpinalDoc-RTD)
- [SymbiFlow.rtfd.io](https://symbiflow.rtfd.io)
- [terostechnology.github.io/terosHDLdoc](https://terostechnology.github.io/terosHDLdoc)
- [tsfpga.com](https://tsfpga.com/)
- [umarcor.github.io/OSVB](https://umarcor.github.io/osvb)
- [vhdl.github.io/pyVHDLModel](https://vhdl.github.io/pyVHDLModel)
- [vunit.github.io](http://vunit.github.io)
- [wishbone-interconnect.org/specs/b3.1](https://wishbone-interconnect.org/specs/b3.1/)
#### Pybtex!
- [pybtex.org](https://pybtex.org)
- [mcmtroffaes/sphinxcontrib-bibtex](https://github.com/mcmtroffaes/sphinxcontrib-bibtex)
- [sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html)
- [sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html)
### Drawbacks
On the one hand, having a fixed LaTeX template makes Sphinx unsuitable for documents that need a pre-defined custom
style.
At the same time, as in AsciiDoc, multiple HTML themes/skins exist, but most of them feel like cosmetic variations of
the same base template.
The de facto standard theme [@rtd-theme] was created several years ago, with a framework and a layout/design that are
getting outdated (last updated on Jan 2015 [@wyrm]).
Moreover, maintainters refuse to support the theme being used outside of the service maintained by themselves.
Some nice and more up to date themes exist, but unfortunately not all of them are open source.
Thankfully, the communty is reacting and recently a very interesting solution based on Bootstrap was published:
Sphinx TYPO3 theme [@typo3].
<aside>
- [sphinx-themes.org](https://sphinx-themes.org/)
- [sphinxthemes.com](https://sphinxthemes.com/)
- [documentation.divio.com](https://documentation.divio.com/) ([evildmp/documentation-system#6](https://github.com/evildmp/documentation-system/issues/6))
</aside>
On the other hand, although arguable, it is a common feeling that reStructuredText is less comfortable to get used to
and to remember than Markdown.
This is coherent with the fact that Markdown is more feature limited.
Nevertheless, this should not be dismissed when approaching writers with different levels of expertise.
Regarding extraction of documentation from sources, Sphinx does a nice job with *docstrings* defined in Python sources.
It can navigate the hierarchy of a package/library and generate the documentation for each module, function, parameter,
etc.
There are language domains for C and C++ too; however support of other languages is quite limited.
[sphinxcontrib-vhdldomain](https://github.com/Paebbels/sphinxcontrib-vhdldomain) and
[pyVHDLParser](https://github.com/Paebbels/pyVHDLParser) are early work to add a domain for VHDL, as an extension to
Sphinx.
<aside>
*W* [Docstring](https://en.wikipedia.org/wiki/Docstring)
- [Sphinx: Domains](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html)
- [Sphinx: More domains](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#more-domains)
</aside>
Even though it is possible to write extensions, it's not something that the average user/developer can do easily.
It is a low-level API that exposes many of the internals and requires a deep understanding of the tool [@sphinx-todo].
In fact, extensions can be builders written from scratch, roles, directives, markup extensions or hooks, all under the
same umbrella.
<aside>
- [Sphinx: Developing extensions for Sphinx](https://www.sphinx-doc.org/en/master/extdev/index.html)
</aside>
With regard to importing Markdown sources, it is supported but feature limited, due to the distinc feature set of the
language.
### ToDo
- Multiple authors
- [executablebooks/MyST-Parser](https://github.com/executablebooks/MyST-Parser)