Convert Typst to RST

Why Convert Typst to RST?

Converting Typst to reStructuredText (RST) connects your typeset content with the Python documentation ecosystem. RST is the standard markup language for Sphinx, the documentation generator used by Python itself, NumPy, Django, Flask, and thousands of other Python projects. By converting your Typst documents to RST, you can publish professional documentation on Read the Docs or any Sphinx-powered site.

RST's directive system provides capabilities that go beyond simple markup. After conversion, you can enhance your RST documents with Sphinx-specific features like autodoc directives for generating API documentation from Python docstrings, cross-references that link across multiple documents, toctree for organizing document hierarchies, and code-block with syntax highlighting for dozens of programming languages.

This conversion is particularly valuable for researchers and developers who maintain both academic papers and software documentation. Write your research content in Typst for its superior mathematical typesetting, then convert to RST for integration into your project's Sphinx documentation. The result is a unified documentation site that combines technical prose with API references.

Read the Docs, the largest free documentation hosting service, processes RST files with Sphinx to generate beautiful HTML documentation. Converting your Typst content to RST lets you publish on Read the Docs with automatic builds from your Git repository. Every push triggers a rebuild, keeping your documentation synchronized with your codebase.

Key Benefits of Converting Typst to RST:

• Sphinx Integration: Build professional documentation sites with Sphinx
• Read the Docs: Publish free documentation with automatic builds
• Python Ecosystem: Standard format for Python project documentation
• Cross-References: Link across documents with Sphinx's reference system
• API Documentation: Combine prose with autodoc-generated API references
• Multi-Format Output: Generate HTML, PDF, EPUB, and man pages from RST
• Code Documentation: Syntax-highlighted code blocks with line numbers

Practical Examples

Example 1: Library Documentation

Input Typst file (docs.typ):

= MyLib Documentation
== Installation
Install *MyLib* using pip:
```bash
pip install mylib
```

== Quick Start
Import and use the _main function_:
```python
from mylib import analyze
result = analyze(data)
```

== API Reference
#table(
  columns: 3,
  [Function], [Parameters], [Returns],
  [analyze()], [data: list], [dict],
  [export()], [path: str], [bool],
)

Output RST file (docs.rst):

MyLib Documentation
===================

Installation
------------
Install **MyLib** using pip:

.. code-block:: bash

   pip install mylib

Quick Start
-----------
Import and use the *main function*:

.. code-block:: python

   from mylib import analyze
   result = analyze(data)

API Reference
-------------
==========  ===========  =======
Function    Parameters   Returns
==========  ===========  =======
analyze()   data: list   dict
export()    path: str    bool
==========  ===========  =======

Example 2: Technical Tutorial

Input Typst file (tutorial.typ):

= Data Processing Pipeline
== Step 1: Load Data
Use the *DataLoader* class to read
CSV files into _structured_ format.

== Step 2: Transform
Apply transformations:
- Normalize columns
- Handle missing values
- Feature engineering

== Step 3: Export
The pipeline supports multiple
output formats:
+ JSON for web APIs
+ CSV for spreadsheets
+ Parquet for big data

Output RST file (tutorial.rst):

Data Processing Pipeline
=======================

Step 1: Load Data
-----------------
Use the **DataLoader** class to read
CSV files into *structured* format.

Step 2: Transform
-----------------
Apply transformations:

- Normalize columns
- Handle missing values
- Feature engineering

Step 3: Export
--------------
The pipeline supports multiple
output formats:

#. JSON for web APIs
#. CSV for spreadsheets
#. Parquet for big data

Example 3: Research Notes for Sphinx Site

Input Typst file (research.typ):

= Optimization Methods
== Gradient Descent
The *gradient descent* update rule:
$ theta_(t+1) = theta_t - eta nabla L(theta_t) $

== Learning Rate Schedules
- Constant: $eta_t = eta_0$
- Step decay: $eta_t = eta_0 dot gamma^(floor(t/s))$
- Cosine annealing: schedule follows
  cosine curve

== Convergence
For _convex_ functions with $L$-smooth
gradients, convergence rate is $O(1/T)$.

Output RST file (research.rst):

Optimization Methods
====================

Gradient Descent
----------------
The **gradient descent** update rule:

.. math::

   \theta_{t+1} = \theta_t - \eta \nabla L(\theta_t)

Learning Rate Schedules
-----------------------
- Constant: :math:`\eta_t = \eta_0`
- Step decay: :math:`\eta_t = \eta_0 \cdot \gamma^{\lfloor t/s \rfloor}`
- Cosine annealing: schedule follows
  cosine curve

Convergence
-----------
For *convex* functions with :math:`L`-smooth
gradients, convergence rate is :math:`O(1/T)`.

Frequently Asked Questions (FAQ)

Q: What is reStructuredText (RST)?

A: reStructuredText is a lightweight markup language designed for technical documentation. It is part of the Python Docutils project and is the standard markup for Sphinx documentation. RST uses underline-based headings, directives for rich content, and roles for inline markup. It powers the documentation for Python itself, NumPy, Django, and thousands of other projects.

Q: Can I use the RST output with Sphinx?

A: Yes! The converted RST is fully compatible with Sphinx. Add the file to your Sphinx project's source directory, include it in the toctree, and run sphinx-build to generate HTML, PDF, or EPUB output. You can enhance the converted RST with Sphinx-specific directives like autodoc, intersphinx, and cross-references.

Q: How are Typst math expressions converted to RST?

A: Typst math is converted to RST's :math: role for inline expressions and the .. math:: directive for display equations. The math content uses LaTeX notation, which Sphinx renders using MathJax in HTML output and native LaTeX in PDF output. Both inline and display math from Typst are faithfully preserved.

Q: How are Typst headings converted to RST?

A: RST uses underline characters for headings rather than prefix characters. Typst's = becomes a title underlined with ===, == becomes underlined with ---, and === becomes underlined with ~~~. The heading hierarchy is preserved, and the underline length matches the heading text.

Q: Can I publish on Read the Docs?

A: Yes! Read the Docs processes RST files with Sphinx automatically. Push your converted RST files to a Git repository, connect it to Read the Docs, and your documentation will be built and hosted for free. Each git push triggers a rebuild, keeping your docs up to date.

Q: How are Typst tables converted to RST tables?

A: Typst's #table() function is converted to RST's grid or simple table format. Simple tables use === separators and spaces for alignment, while grid tables use + and | characters for cell borders. The table structure and content are preserved for correct Sphinx rendering.

Q: Are code blocks preserved in the conversion?

A: Yes, Typst code blocks are converted to RST's .. code-block:: directive with the language identifier preserved. This enables syntax highlighting in Sphinx output for Python, JavaScript, Bash, and many other languages. Both inline code and multi-line blocks are handled correctly.

Q: What about Typst's scripting constructs?

A: Typst scripting (#let, #if, #for) is resolved during conversion. The RST output contains the final rendered content, not scripting code. Variables are expanded, conditionals are resolved, and loops produce their complete output. RST itself does not have scripting capabilities, so all dynamic content is flattened.