Hey r/Python!
I wanted to share a project I've been working on: an Interactive reStructuredText Tutorial.
What My Project Does
It's a web-based, hands-on tutorial designed to teach reStructuredText (reST), the markup language used extensively in Python documentation (like Sphinx, docstrings, etc.). The entire tutorial, including the reST rendering, runs directly in your browser using PyScript and Pyodide.
You get a lesson description on one side and an interactive editor on the other. As you type reST in the editor, you see the rendered HTML output update instantly. It covers topics from basic syntax and inline markup to more complex features like directives, roles, tables, and figures.
There's also a separate Playground page for free-form experimentation.
Why I Made It
While the official reStructuredText documentation is comprehensive, I find that learning markup languages is often easier with immediate, interactive feedback. I wanted to create a tool where users could experiment with reST syntax and see the results without needing any local setup. Building it with PyScript was also a fun challenge to see how much could be done directly in the browser with Python.
Target Audience
This is for anyone who needs to learn or brush up on reStructuredText:
-
Python developers writing documentation or docstrings.
-
Users of Sphinx or other Docutils-based tools.
-
Technical writers.
-
Anyone interested in reStructuredText
Key Features
-
Interactive Editor
-
Structured Lessons
-
Instant Feedback
-
Playground with "Share" button (like pastebin)
-
Dark Mode 😉
Comparison to Other Tools
I didn't find any other interactive reST tutorials, or even reST playgrounds.
You still better read the official documentation, but my project will help you get started and understand the basics.
Links
-
Project Website
-
Playground
-
GitHub Repo
I'd love to hear your feedback!
Thanks!
I'd like to extend upon the answer from Gareth Latty. "What you probably want is the parser at docutils.parsers.rst" is a good starting point of the answer, but what's next? Namely:
How to parse restructuredtext in python?
Below is the exact answer for Python 3.6 and docutils 0.14:
import docutils.nodes
import docutils.parsers.rst
import docutils.utils
import docutils.frontend
def parse_rst(text: str) -> docutils.nodes.document:
parser = docutils.parsers.rst.Parser()
components = (docutils.parsers.rst.Parser,)
settings = docutils.frontend.OptionParser(components=components).get_default_values()
document = docutils.utils.new_document('<rst-doc>', settings=settings)
parser.parse(text, document)
return document
And the resulting document can be processed using, for example, below, which will print all references in the document:
class MyVisitor(docutils.nodes.NodeVisitor):
def visit_reference(self, node: docutils.nodes.reference) -> None:
"""Called for "reference" nodes."""
print(node)
def unknown_visit(self, node: docutils.nodes.Node) -> None:
"""Called for all other node types."""
pass
Here's how to run it:
doc = parse_rst('spam spam lovely spam')
visitor = MyVisitor(doc)
doc.walk(visitor)
Docutils does indeed contain the tools to do this.
What you probably want is the parser at docutils.parsers.rst
See this page for details on what is involved. There are also some examples at docutils/examples.py - particularly check out the internals() function, which is probably of interest.