Skip to main content
Documentation Status https://github.com/MacHu-GWU/rstobj-project/actions/workflows/main.yml/badge.svg https://codecov.io/gh/MacHu-GWU/rstobj-project/branch/main/graph/badge.svg https://img.shields.io/pypi/v/rstobj.svg https://img.shields.io/pypi/l/rstobj.svg https://img.shields.io/pypi/pyversions/rstobj.svg https://img.shields.io/badge/✍️_Release_History!--None.svg?style=social&logo=github https://img.shields.io/badge/⭐_Star_me_on_GitHub!--None.svg?style=social&logo=github
https://img.shields.io/badge/Link-API-blue.svg https://img.shields.io/badge/Link-Install-blue.svg https://img.shields.io/badge/Link-GitHub-blue.svg https://img.shields.io/badge/Link-Submit_Issue-blue.svg https://img.shields.io/badge/Link-Request_Feature-blue.svg https://img.shields.io/badge/Link-Download-blue.svg

Welcome to rstobj Documentation

https://rstobj.readthedocs.io/en/latest/_static/rstobj-logo.png

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:

  1. Use .. include-all-image:: to automatically scan image file under a directory, create .. image:: directive and organize everything in a table.

  2. Separate comment and value of the config file, automatically create an document for a config file.

  3. …

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)

Source distribution for rstobj 2.0.1
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)

Table of built distributions (wheels) for rstobj 2.0.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page