Welcome to rstobj Documentation
rstobj is a library that construct Restructured Text markup or directives from Python Code. rstobj is based on jinja2.
The idea behind rstobj:
RestructuredText is super powerful, way more powerful than markdown. But have you ever think of customize YOUR OWN markup or directive and do some magic?
Have you think of automatically generate customized document from your code or tabulate data?
Sphinx Doc is the ultimate doc build tool. With rstobj, you can easily create your own markup / directive, and hide complex workflow behind a single markup / directive, then use it when you need it. Here’s some ideas:
Use .. include-all-image:: to automatically scan image file under a directory, create .. image:: directive and organize everything in a table.
Separate comment and value of the config file, automatically create an document for a config file.
…
I have a Blog Post to share how to create a sphinx doc extension in 50 lines and customize your own directive (Sorry, its written in Chinese).
Example:
import rstobj.api as rstobj
header = rstobj.markup.Header(title="Section1", header_level=1, auto_label=True)
print(header.render())
ltable = rstobj.directives.ListTable(
data=[["id", "name"], [1, "Alice"], [2, "Bob"]],
title="Users",
header=True,
)
print(ltable.render())
Output:
.. _Section1:
Section1
========
.. list-table:: Users
:header-rows: 1
:stub-columns: 0
* - id
- name
* - 1
- Alice
* - 2
- Bob
See the Rendering Gallery for every supported markup and directive, with its Python code, its output, and how it renders.
I recommend to use this in your jinja2 template, content of output.rst:
{{ header.render() }}
{{ ltable.render() }}
And use rstobj with sphinx-jinja library https://pypi.org/project/sphinx-jinja/ in sphinx doc project.
Supported directives:
.. image::
.. list-table::
.. contents::
.. code-block::
.. include::
Supported markup:
Header:
.. _ref-label: Title =====
URL: `Text <Target>`_
Reference: :ref:`Text <Target>`
If you need more features, please submit an issue to https://github.com/MacHu-GWU/rstobj-project/issues
Install
rstobj is released on PyPI, so all you need is:
$ pip install rstobj
To upgrade to latest version:
$ pip install --upgrade rstobj
Use with AI Coding Agents
This repo ships an Agent Skill that documents the public API of rstobj, so an AI coding agent such as Claude Code can use the library without reading its source. It lives in .claude/skills/pypi-rstobj. To use it in your project, copy it into your project’s .claude/skills/ folder. Run this from your project’s root:
$ git clone --depth 1 https://github.com/MacHu-GWU/rstobj-project.git /tmp/rstobj-project
$ mkdir -p .claude/skills
$ cp -R /tmp/rstobj-project/.claude/skills/pypi-rstobj .claude/skills/
Metadata
Release files for rstobj 2.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rstobj-2.0.1.tar.gz | 20.4 kB | Without provenance | Details for rstobj-2.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rstobj-2.0.1-py3-none-any.whl | Python 3 | none | any | Details for rstobj-2.0.1-py3-none-any.whl |
Total release size: 45.0 kB
Release files / rstobj-2.0.1.tar.gz
| Download URL | rstobj-2.0.1.tar.gz |
|---|---|
| Size | 20.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b29d57bcfdf6b86e1704b8407afcdaf2f94cc35e4ca51bdaacf3badfd8729e3d
|
|
BLAKE2b-256 checksum How to use checksums |
72d392ca15cc269318be8659565838f661d251aab8d951455fde23351ef03ef7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / rstobj-2.0.1-py3-none-any.whl
| Download URL | rstobj-2.0.1-py3-none-any.whl |
|---|---|
| Size | 24.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d18263ce08b3591b568dd9d96fffc88d06b5182c6e2af053791411d2a80130a5
|
|
BLAKE2b-256 checksum How to use checksums |
75687185397331fe6cf7b1230d969dedc1023e547fc371f28c406f296357a866
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for rstobj 2.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.