Post on 21-Jan-2018
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 formatSphinx 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 propisal to -policy mailing list● ITP: sphinx-intl● make “debian doc” theme for sphinx (needs help)