Migrating from Sphinx-A4Doc¶
Install
sphinx-syntax
:$ pip install 'sphinx-syntax'
In your
conf.py
:replace
"sphinx_a4doc"
extension with"sphinx_syntax"
.extensions = [ "sphinx_syntax", ]
replace
a4_base_path
withsyntax_base_path
.Paths are now resolved relative to directory of
conf.py
, so you can removedirname(__file__)
.set
syntax_a4doc_compat_links = True
to generate link anchors compatible with Sphinx-A4Doc’s naming. This will keep old links to your documentation working.if you’re building LaTeX documentation, add an extension to convert SVGs to PDFs:
$ pip install 'sphinxcontrib-svg2pdfconverter[CairoSVG]'
extensions = [ # ... "sphinxcontrib.cairosvgconverter", ]
Tip
See extension’s README if you want to use Inkscape or RSVG instead of CairoSVG.
Convert your RST files with our utility (a.k.a. a bunch of regexes).
Check expected diff:
$ python -m sphinx_syntax.ext.antlr4.sphinx_a4doc_convert --diff .
Apply diff:
$ python -m sphinx_syntax.ext.antlr4.sphinx_a4doc_convert --run .
If you were using
a4_railroad_diagram.css
ora4_railroad_diagram_latex.css
, rename them tosyntax-diagrams-latex.css
andsyntax-diagrams.css
.
Differences between Sphinx Syntax and Sphinx-A4Doc¶
Sphinx Syntax is a refactored version of Sphinx-A4Doc.
Domain
a4
was renamed tosyntax
. This unties documentation from implementation details, allowing us to support other parser generators in future.Some directives and flags were renamed, the automatic conversion script will take care of those.
Syntax diagrams can now be rendered using ASCII art, so they’ll show up in text and man page output.
Diagram rendering engine was reworked. It includes more optimizations for optional elements, recursive rules, and so on. For example, it can now collapse nested optionals so that they use less vertical space:
HEX HEX HEX HEX Options for
syntax:diagram
were prefixed withtext-
andsvg-
:Old name
New name
:end-class:
not renamed
:padding:
:svg-padding:
,:text-padding:
:vertical-separation:
:svg-vertical-choice-separation:
,:svg-vertical-seq-separation:
:horizontal-separation:
:svg-horizontal-seq-separation:
:arc-radius:
:svg-arc-radius:
,:svg-arc-margin:
:translate-half-pixel:
removed
:internal-alignment:
removed
:character-advance:
removed, available from
conf.py
:max-width:
removed
:literal-rendering:
not renamed, but only affects
syntax:lexer-diagram
andsyntax:parser-diagram
now:cc-to-dash:
not renamed, but only affects
syntax:lexer-diagram
andsyntax:parser-diagram
now:alt:
not renamed, but only affects SVG accessibility attributes now
Directives
a4:autorule
,docstring-marker
, andmembers-marker
were removed. As far as I can see, there’s no code on GitHub that uses them.