Convert JIRA to RST

Why Convert JIRA to RST?

Converting Jira markup to reStructuredText enables you to integrate Jira project documentation into Sphinx documentation projects. RST is the standard format for Python documentation, powering thousands of projects hosted on Read the Docs.

RST offers powerful features that enhance your converted content, including cross-references between documents, directive-based admonitions (notes, warnings, tips), and the ability to generate HTML, PDF, and EPUB output from a single source. These capabilities go well beyond what Jira markup provides.

This conversion is particularly valuable for Python development teams that use Jira for project management and Sphinx for documentation. It bridges the gap between project tracking and technical documentation, allowing Jira content to be incorporated into comprehensive documentation sites.

Key Benefits of Converting JIRA to RST:

• Sphinx Integration: Use converted content directly in Sphinx documentation projects
• Read the Docs: Publish Jira documentation on Read the Docs for free
• Cross-References: Link between documents with RST cross-reference roles
• Admonitions: Jira panels become RST note, warning, and tip directives
• Code Blocks: Syntax-highlighted code blocks with language specification
• Multi-Format: Generate HTML, PDF, EPUB from the RST source
• Python Ecosystem: Standard format for Python package documentation

Practical Examples

Example 1: API Documentation to RST

Input JIRA file (api.jira):

h1. User Management API

h2. Create User
Creates a new user account with the specified details.

||Parameter||Type||Required||
|username|string|Yes|
|email|string|Yes|
|role|string|No|

{code:python}
import requests

response = requests.post("/api/users", json={
    "username": "john_doe",
    "email": "[email protected]",
    "role": "editor"
})
{code}

{panel:title=Note}
Email addresses must be unique across all accounts.
{panel}

Output RST file (api.rst):

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

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

Creates a new user account with the specified details.

=========  ======  ========
Parameter  Type    Required
=========  ======  ========
username   string  Yes
email      string  Yes
role       string  No
=========  ======  ========

.. code-block:: python

   import requests

   response = requests.post("/api/users", json={
       "username": "john_doe",
       "email": "[email protected]",
       "role": "editor"
   })

.. note::

   Email addresses must be unique across all accounts.

Example 2: Architecture Document to RST

Input JIRA file (architecture.jira):

h1. System Architecture

h2. Overview
The system uses a *microservices* architecture with _event-driven_ communication between services.

h2. Components
* *API Gateway* - Routes incoming requests
* *Auth Service* - Handles authentication
* *Data Service* - Manages data storage

h2. Communication
# Client sends request to API Gateway
# Gateway validates authentication token
# Request is forwarded to target service
# Response is returned to client

{quote}
All inter-service communication uses gRPC for performance.
{quote}

Output RST file (architecture.rst):

System Architecture
===================

Overview
--------

The system uses a **microservices** architecture
with *event-driven* communication between services.

Components
----------

* **API Gateway** - Routes incoming requests
* **Auth Service** - Handles authentication
* **Data Service** - Manages data storage

Communication
-------------

#. Client sends request to API Gateway
#. Gateway validates authentication token
#. Request is forwarded to target service
#. Response is returned to client

   All inter-service communication uses gRPC
   for performance.

Example 3: Setup Guide to RST

Input JIRA file (setup.jira):

h1. Development Setup

h2. Prerequisites
* Python 3.10 or higher
* PostgreSQL 14+
* Redis server

h2. Installation
{code:bash}
git clone https://github.com/team/project.git
cd project
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
{code}

h2. Configuration
||Variable||Description||Default||
|DATABASE_URL|PostgreSQL connection|postgresql://localhost/mydb|
|REDIS_URL|Redis connection|redis://localhost:6379|
|DEBUG|Debug mode|false|

{panel:title=Warning}
Never enable DEBUG mode in production environments.
{panel}

Output RST file (setup.rst):

Development Setup
=================

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

* Python 3.10 or higher
* PostgreSQL 14+
* Redis server

Installation
------------

.. code-block:: bash

   git clone https://github.com/team/project.git
   cd project
   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

Configuration
-------------

============  ======================  =============================
Variable      Description             Default
============  ======================  =============================
DATABASE_URL  PostgreSQL connection   postgresql://localhost/mydb
REDIS_URL     Redis connection        redis://localhost:6379
DEBUG         Debug mode              false
============  ======================  =============================

.. warning::

   Never enable DEBUG mode in production environments.

Frequently Asked Questions (FAQ)

Q: How are Jira headings converted to RST?

A: Jira headings are converted to RST's underline-based heading style. h1. becomes a title with = underline, h2. uses - underline, h3. uses ~ underline, following standard RST heading hierarchy conventions.

Q: Can I use the output with Sphinx?

A: Yes. The output is valid RST that can be included directly in a Sphinx documentation project. Add the file to your Sphinx source directory and reference it in the toctree directive to include it in your documentation build.

Q: How are Jira tables converted to RST tables?

A: Jira tables are converted to RST simple table syntax using = characters for borders. Headers are properly separated, and columns are aligned for readability. RST grid tables may be used for more complex table structures.

Q: Are code blocks properly formatted?

A: Yes. Jira {code:language}...{code} blocks are converted to RST code-block directives (.. code-block:: language) with proper indentation, enabling syntax highlighting in the rendered output.

Q: How are Jira panels converted?

A: Jira {panel} blocks are converted to RST admonition directives. Panels with titles like "Note", "Warning", or "Tip" are mapped to the corresponding RST admonitions (.. note::, .. warning::, .. tip::).

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

A: Yes. Read the Docs natively supports RST files through Sphinx. Add the converted RST to your Sphinx project, push to GitHub, and Read the Docs will automatically build and host your documentation.

Q: How does bold and italic text convert?

A: Jira bold (*text*) becomes RST bold (**text**), and Jira italic (_text_) becomes RST italic (*text*). RST uses different numbers of asterisks for bold and italic, unlike Jira's mixed syntax.

Q: Are RST cross-references added automatically?

A: The initial conversion preserves Jira links as RST external hyperlinks. You can manually add RST-specific cross-references (using :ref: and :doc: roles) after conversion to link between documents in your Sphinx project.