Convert DOCBOOK to RST

Why Convert DocBook to RST?

Converting DocBook to RST (reStructuredText) migrates structured XML documentation into the format that powers the Python documentation ecosystem. RST is the native format of Sphinx, the documentation generator used by Python, Django, Flask, NumPy, and thousands of other projects hosted on Read the Docs.

DocBook and RST share many capabilities: both support admonitions, cross-references, code blocks with syntax highlighting, tables, and multi-document projects. This makes the conversion particularly clean -- DocBook <note> becomes .. note::, <programlisting> becomes .. code-block::, and <xref> becomes :ref: roles. The semantic richness of DocBook maps well to RST's directive system.

Sphinx extends RST with powerful features like automatic API documentation from Python docstrings (autodoc), cross-project references (intersphinx), and a table-of-contents tree (toctree) that assembles multiple RST files into a cohesive documentation site. Converting DocBook to RST unlocks these capabilities for your documentation.

The Linux kernel documentation itself migrated from DocBook to RST/Sphinx, demonstrating that RST can handle the same scale and complexity as DocBook while offering a more accessible authoring experience. This conversion enables similar migrations for organizations that want to modernize their documentation toolchain.

Key Benefits of Converting DocBook to RST:

• Sphinx Integration: Build beautiful documentation sites with Sphinx
• Read the Docs: Free hosting and automated builds on RTD
• Python Ecosystem: Match the standard used by Python libraries
• Admonition Support: Native note, warning, and tip directives
• Cross-References: Rich linking with :ref:, :doc:, and intersphinx
• API Autodoc: Generate API docs from Python source code
• Multi-Format Output: HTML, PDF, EPUB, and man pages from RST

Practical Examples

Example 1: API Documentation

Input DocBook file (api.xml):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Authentication API</title>
  <para>Use JWT tokens for authentication.</para>
  <programlisting language="python">
import jwt
token = jwt.encode(payload, secret)</programlisting>
  <warning>
    <para>Never expose your secret key.</para>
  </warning>
</section>

Output RST file (api.rst):

Authentication API
==================

Use JWT tokens for authentication.

.. code-block:: python

   import jwt
   token = jwt.encode(payload, secret)

.. warning::

   Never expose your secret key.

Example 2: Configuration with Table

Input DocBook file (config.xml):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Configuration Options</title>
  <table>
    <tgroup cols="3">
      <thead><row>
        <entry>Option</entry>
        <entry>Type</entry>
        <entry>Default</entry>
      </row></thead>
      <tbody>
        <row><entry>debug</entry>
        <entry>bool</entry>
        <entry>False</entry></row>
        <row><entry>port</entry>
        <entry>int</entry>
        <entry>8000</entry></row>
      </tbody>
    </tgroup>
  </table>
</section>

Output RST file (config.rst):

Configuration Options
=====================

.. list-table::
   :header-rows: 1

   * - Option
     - Type
     - Default
   * - debug
     - bool
     - False
   * - port
     - int
     - 8000

Example 3: Cross-Referenced Guide

Input DocBook file (guide.xml):

<section xmlns="http://docbook.org/ns/docbook"
         xml:id="installation">
  <title>Installation</title>
  <orderedlist>
    <listitem><para>Download the package</para></listitem>
    <listitem><para>Run the installer</para></listitem>
    <listitem><para>Verify the installation</para></listitem>
  </orderedlist>
  <para>For configuration, see
  <xref linkend="configuration"/>.</para>
</section>

Output RST file (guide.rst):

.. _installation:

Installation
============

1. Download the package
2. Run the installer
3. Verify the installation

For configuration, see :ref:`configuration`.

Frequently Asked Questions (FAQ)

Q: Can I build a Sphinx site from the converted RST files?

A: Yes. The converted RST files are fully compatible with Sphinx. Create a conf.py configuration file and an index.rst with a toctree directive that references your converted files, then run "sphinx-build" to generate HTML documentation. The output can be hosted on Read the Docs for free.

Q: How are DocBook admonitions mapped to RST?

A: DocBook admonitions map directly to RST directives: <note> becomes .. note::, <warning> becomes .. warning::, <tip> becomes .. tip::, <caution> becomes .. caution::, and <important> becomes .. important::. RST has native support for all these admonition types.

Q: Are cross-references preserved in the RST output?

A: Yes. DocBook xml:id attributes become RST labels (.. _labelname:) and <xref> elements become :ref:`labelname` references. This preserves the cross-reference system across the documentation. Sphinx resolves these references during the build process.

Q: How are code blocks converted?

A: DocBook <programlisting language="python"> becomes RST .. code-block:: python with proper indentation. The language tag enables syntax highlighting in the Sphinx output. Inline code (<code>) is converted to RST backtick notation ``code``.

Q: Can I host the RST documentation on Read the Docs?

A: Yes. Read the Docs (readthedocs.org) provides free hosting for Sphinx documentation. Connect your repository, and Read the Docs will automatically build and host your documentation whenever you push changes. It supports custom domains, versioning, and PDF downloads.

Q: How are DocBook tables represented in RST?

A: DocBook tables are converted to RST list-table directives or grid tables. List-table is more readable in the source and easier to maintain. For complex tables with spanning, grid table syntax is used. Both formats render identically in the Sphinx HTML output.

Q: Is the Linux kernel documentation migration relevant?

A: Yes. The Linux kernel migrated its documentation from DocBook to RST/Sphinx starting in 2016. This real-world migration demonstrates that RST can handle the same complexity and scale as DocBook while providing a more accessible authoring experience and a modern documentation website.

Q: Can I convert RST back to DocBook?

A: Yes. Both pandoc and Sphinx's DocBook builder can generate DocBook XML from RST. The conversion preserves headings, lists, tables, code blocks, and admonitions. This makes round-trip editing possible when different teams use different documentation formats.