Convert RST to XML

Why Convert RST to XML?

Converting reStructuredText (RST) documents to XML transforms human-readable documentation into a structured, machine-processable format. XML output preserves the complete document structure, making it ideal for integration with content management systems, publishing pipelines, and data processing workflows.

XML's self-describing nature means every element of your RST document - headers, paragraphs, lists, code blocks - is explicitly tagged and queryable. This enables powerful transformations using XSLT, selective extraction with XPath, and validation against schemas.

The conversion is particularly valuable for enterprise documentation workflows. Many organizations use XML-based systems like DITA, DocBook, or custom schemas for single-source publishing. Converting RST to XML allows integration of Python documentation into these broader content strategies.

XML also serves as an intermediate format for further conversions. From XML, you can transform to HTML, PDF, EPUB, or any other format using XSLT stylesheets. This makes XML a powerful hub in multi-format publishing pipelines.

Key Benefits of Converting RST to XML:

• Structured Data: Complete document structure in queryable format
• XSLT Transformation: Convert to any output format with stylesheets
• XPath Queries: Extract specific content programmatically
• Schema Validation: Ensure document structure compliance
• Enterprise Integration: Works with CMS and publishing systems
• DocBook Compatibility: Standard XML documentation format
• API Processing: Parse and manipulate with any XML library

Practical Examples

Example 1: Document Structure

Input RST file (guide.rst):

Installation Guide
==================

Requirements
------------

Before installing, ensure you have:

* Python 3.8+
* pip installed
* Network access

Output XML file (guide.xml):

<?xml version="1.0" encoding="UTF-8"?>
<document>
  <section ids="installation-guide">
    <title>Installation Guide</title>
    <section ids="requirements">
      <title>Requirements</title>
      <paragraph>Before installing, ensure you have:</paragraph>
      <bullet_list bullet="*">
        <list_item><paragraph>Python 3.8+</paragraph></list_item>
        <list_item><paragraph>pip installed</paragraph></list_item>
        <list_item><paragraph>Network access</paragraph></list_item>
      </bullet_list>
    </section>
  </section>
</document>

Example 2: Code and Directives

Input RST file (api.rst):

API Usage
=========

Here is a basic example:

.. code-block:: python

   import mylib
   result = mylib.process(data)

.. note::
   Always handle exceptions appropriately.

Output XML file (api.xml):

<?xml version="1.0" encoding="UTF-8"?>
<document>
  <section ids="api-usage">
    <title>API Usage</title>
    <paragraph>Here is a basic example:</paragraph>
    <literal_block language="python" xml:space="preserve">
import mylib
result = mylib.process(data)
    </literal_block>
    <note>
      <paragraph>Always handle exceptions appropriately.</paragraph>
    </note>
  </section>
</document>

Example 3: Tables and References

Input RST file (config.rst):

Configuration
=============

See the `official docs <https://example.com>`_ for details.

+---------+---------+
| Option  | Default |
+=========+=========+
| debug   | false   |
+---------+---------+
| timeout | 30      |
+---------+---------+

Output XML file (config.xml):

<?xml version="1.0" encoding="UTF-8"?>
<document>
  <section ids="configuration">
    <title>Configuration</title>
    <paragraph>See the
      <reference refuri="https://example.com">official docs</reference>
      for details.
    </paragraph>
    <table>
      <thead>
        <row><entry>Option</entry><entry>Default</entry></row>
      </thead>
      <tbody>
        <row><entry>debug</entry><entry>false</entry></row>
        <row><entry>timeout</entry><entry>30</entry></row>
      </tbody>
    </table>
  </section>
</document>

Frequently Asked Questions (FAQ)

Q: What XML schema does the output follow?

A: The default output follows the Docutils native XML schema, which maps directly to RST document structure. This can be transformed to DocBook, DITA, or custom schemas using XSLT. Pandoc can also output DocBook XML directly.

Q: Can I validate the XML output?

A: Yes! The Docutils XML output can be validated against its DTD or schema. If converting to DocBook or DITA, those schemas can validate the transformed output. Use xmllint, Oxygen XML, or similar tools for validation.

Q: How do I transform XML to HTML or PDF?

A: Use XSLT stylesheets to transform XML to HTML, XSL-FO (for PDF), or other formats. Tools like Saxon, xsltproc, or Apache FOP can process these transformations. DocBook has ready-made stylesheets for multiple output formats.

Q: How do I query specific content from the XML?

A: Use XPath queries to extract specific elements. For example, `//section/title` gets all section titles, `//literal_block[@language='python']` gets Python code blocks. Libraries like lxml (Python) or javax.xml.xpath (Java) support XPath.

Q: Is the XML output the same as Sphinx's XML builder?

A: Similar but not identical. This converter produces Docutils-style XML. Sphinx's XML builder adds Sphinx-specific elements like index entries and cross-reference metadata. Both preserve document structure fully.

Q: Can I convert XML back to RST?

A: Yes, using XSLT to transform Docutils XML back to RST text. Pandoc can also convert from DocBook XML to RST. Round-trip conversion preserves structure but may have minor formatting differences.

Q: How do I process the XML in Python?

A: Use the built-in xml.etree.ElementTree for simple processing, or lxml for full XPath/XSLT support. Example: `tree = etree.parse('doc.xml'); titles = tree.xpath('//title/text()')`

Q: What's the difference from converting to XHTML?

A: XML preserves the semantic document structure (sections, paragraphs, lists as concepts), while XHTML converts to presentation markup (div, p, ul). XML is better for processing; XHTML is ready for web display.