Convert SXW to RST

Why Convert SXW to RST?

Converting SXW to RST transforms legacy StarOffice/OpenOffice.org Writer documents into the standard documentation format used by the Python ecosystem. reStructuredText is the foundation of Sphinx, the documentation generator that powers Read the Docs and the documentation for Python itself, Django, Flask, and thousands of other projects.

SXW documents from the StarOffice era may contain technical documentation, API descriptions, or project specifications that need to be migrated into modern documentation systems. RST format enables these documents to be integrated into Sphinx documentation projects with full cross-referencing, table of contents generation, and multi-format output.

RST offers features specifically designed for technical documentation that SXW cannot match: directives for admonitions (warnings, notes, tips), code blocks with syntax highlighting, API autodoc integration, and a powerful cross-referencing system that links between documents, sections, and code elements.

Our converter reads the SXW archive, extracts the document content and structure, and generates properly formatted RST with appropriate heading decorations, list syntax, emphasis markup, and directives. The output is immediately usable with Sphinx and can be published on Read the Docs.

Key Benefits of Converting SXW to RST:

• Sphinx Integration: Use directly in Sphinx documentation projects
• Python Ecosystem: Standard format for Python package documentation
• Read the Docs: Publish on the free documentation hosting platform
• Cross-References: Link between documents, sections, and code elements
• Multi-Format Output: Generate HTML, PDF, EPUB from single RST source
• Version Control: Track documentation changes in Git with meaningful diffs

Practical Examples

Example 1: API Documentation

Input SXW file (api_docs.sxw) containing:

User Management API

Create User
Creates a new user account with the
specified username and email address.

Parameters:
username - required string
email - required string
role - optional string (default: user)

Output RST file (api_docs.rst):

User Management API
====================

Create User
-----------

Creates a new user account with the
specified username and email address.

:Parameters:

* **username** - required string
* **email** - required string
* **role** - optional string (default: user)

Example 2: Installation Guide

Input SXW file (install.sxw) containing:

Installation Guide

Prerequisites
Python 3.8 or higher
pip package manager
PostgreSQL 13+

Quick Start
Install the package from PyPI.
Configure the database connection.
Run the database migrations.

Output RST file (install.rst):

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

Prerequisites
-------------

* Python 3.8 or higher
* pip package manager
* PostgreSQL 13+

Quick Start
-----------

Install the package from PyPI.
Configure the database connection.
Run the database migrations.

Example 3: Configuration Reference

Input SXW file (config_ref.sxw) containing:

Configuration Reference

Server Settings
DEBUG: Enable debug mode (True/False)
PORT: Server port number (default: 8000)
WORKERS: Number of worker processes

Database Settings
DB_ENGINE: Database backend (postgresql)
DB_NAME: Database name
DB_HOST: Database server hostname

Output RST file (config_ref.rst):

Configuration Reference
=======================

Server Settings
---------------

* **DEBUG**: Enable debug mode (True/False)
* **PORT**: Server port number (default: 8000)
* **WORKERS**: Number of worker processes

Database Settings
-----------------

* **DB_ENGINE**: Database backend (postgresql)
* **DB_NAME**: Database name
* **DB_HOST**: Database server hostname

Frequently Asked Questions (FAQ)

Q: What is an SXW file?

A: SXW is a document format from StarOffice and OpenOffice.org Writer. Introduced in 2002, it is a ZIP archive containing XML files. It was superseded by ODT in 2005 but remains readable by LibreOffice.

Q: What is reStructuredText (RST)?

A: reStructuredText is a lightweight markup language created by David Goodger in 2001. It is the standard documentation format for the Python ecosystem and is processed by Docutils and Sphinx to produce HTML, PDF, and other output formats. RST uses underline decoration for headings, asterisks for lists, and directives for advanced content.

Q: Can I use the RST output with Sphinx?

A: Yes. The generated RST is fully compatible with Sphinx. You can add the file to a Sphinx project's source directory and include it in the table of contents tree (toctree). Sphinx will process it along with your other documentation files to produce HTML, PDF, or EPUB output.

Q: How are headings converted to RST?

A: SXW heading levels are converted to RST heading decorations. In RST, headings use underline (and optional overline) characters: = for top-level, - for second level, ~ for third level, and so on. The converter selects appropriate decoration characters for each heading level.

Q: Are tables preserved in the RST output?

A: Yes. Tables from SXW documents are converted to RST grid table or simple table syntax. RST supports complex table structures with column spans and row spans, though some complex SXW table formatting may be simplified during conversion.

Q: Can I publish the RST output on Read the Docs?

A: Yes. Read the Docs is a free documentation hosting platform that builds and hosts Sphinx documentation. Once your RST file is part of a Sphinx project and pushed to a Git repository, Read the Docs can automatically build and publish it.

Q: How does RST compare to Markdown?

A: RST is more powerful than Markdown for technical documentation, offering directives, roles, cross-referencing, and extensibility through custom plugins. However, Markdown is simpler and more widely adopted outside the Python ecosystem. RST is the standard for Python projects using Sphinx.

Q: What happens to images in the SXW document?

A: Images are referenced using RST's image directive (.. image:: path/to/image.png). The image files need to be extracted separately from the SXW archive and placed in the documentation project's image directory for the references to work correctly.