challenge:

convert debian-policy doc from docbook to Sphinx

proposal: move forward to modern environment

​

Hideki Yamane <henrich@debian.org>

Why move away from docbook?

• Adding i18n support to docbook xml is so complicated
• couldn’t do that with old debiandoc-sgml, at least
• I want to merge Japanese translation to upstream
• It’s harder to edit/read than other markup language� (such as Markdown, Asciidoc, reStructuredText)
• Less effort, more profit
• Lower barrier for newcomers

Why Sphinx?

• Linux Kernel documents have already moved from docbook to Sphinx
• They’ve already checked markdown and asciidoc,�but finally choosed reStructuredText and Sphinx
• see https://youtu.be/jY_C-Z0qMSo
• I know upstream maintainer, so I can ask him about its feature via twitter at any time :-)

Sphinx?

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

Debian Policy: output format

Sphinx supports:

HTML, LaTeX (PDF), ePub,�Plain Text, Texinfo, manual pages�

convert docbook .xml to .rst via pandoc

• It’s fairly easy!
• $ sudo apt install pandoc
• $ pandoc -f docbook -t rst policy.xml -o policy.rst

​

Pandoc issue

• Generates footnote as static number, not autonumbered →sed
• docbook generated footnote for each section, but pandoc puts only one huge footnote�→manual edit

Pandoc issue

• Break Internal Hyperlink reference

- `section\_title <#s-fhs>`__�+ :ref:`s-fhs`

- ```Format`` <#s-f-Format>`__�+ :ref:`Format <s-f-Format>`

-`Control files and their fields <#ch-controlfields>`__.�+:doc:`Control files and their fields <ch-controlfields>`.

Pandoc issue

• Lose information
• <!ENTITY changesversion "1.8">�The format described in this document is <literal>&changesversion;</literal>.
• The format described in this document is ````.

Pandoc issue

• Link tag is bit strange
• <https://www.example.com/>`__
• expected: <https://www.example.com/>`_� (last _ is single)

Demo: Pandoc issue

Sphinx: strong point

• i18n: established way to add new language support
• $ sudo apt install python-pip
• $ pip install sphinx-intl; export PATH=~/.local/bin:$PATH
• add locale setting to conf.py (edit)
• $ make gettext
• $ sphinx-intl update -p build/locale -l ja -l <lang2> ..
• translate source/locale/<lang>/LC_MESSAGES/<file>.po (edit)
• make html
• cd source && sphinx-build . ../build/html -D language='ja' -D html_file_suffix=.ja.html

see http://www.sphinx-doc.org/en/stable/intl.html

Sphinx: modern look

Sphinx: “theme” feature

You can change HTML visual via“jinja2” template (I’m not sure…)�see http://www.sphinx-doc.org/en/stable/theming.html

​

Limitation in Sphinx compared to docbook

• No Appendix support
• footnote number does not continue for whole document�→Upstream kindly create & proposed extension! :)
• Cannot use nested tag
• :ref:```Maintainer`` <s-f-Maintainer>`

Demo

$ sudo apt install python-sphinx python-pip�$ pip install sphinx-intl; export PATH=~/.local/bin:$PATH�$ git clone https://github.com/henrich/policydoc�$ cd policydoc �$ git checkout restructure�$ make -f sphinx-makefile html��$ cd source; sphinx-build . ../build/html -D language='ja' -D html_file_suffix=.ja.html

Not yet

• PDF output check, compare to docbook one
• $ sudo apt install latexmk; make latexpdf
• ePub output check
• $ make epub

… Maybe need to discuss sphinx upstream to improve it.

Conclusion→Next step?

• It’s (almost) ready to use sphinx for debian-policy documentation
• But needs improvement for support multi language output support
• Give a proposal to -policy mailing list
• ITP: sphinx-intl
• make “debian doc” theme for sphinx (needs help)