rstobj 1.2.1__tar.gz → 2.0.1__tar.gz

rstobj-2.0.1/AUTHORS.rst

@@ -0,0 +1,15 @@
+.. _about_author:
+
+About the Author
+------------------------------------------------------------------------------
+::
+
+   (\ (\
+   ( -.-)o
+   o_(")(")
+
+**Sanhe Hu** is a seasoned software engineer with a deep passion for Python development since 2010. As an author and maintainer of `150+ open-source Python projects <https://pypi.org/user/machugwu/>`_, with over `15 million monthly downloads <https://github.com/MacHu-GWU>`_, I bring a wealth of experience to the table. As a Senior Solution Architect and Subject Matter Expert in AI, Data, Amazon Web Services, Cloud Engineering, DevOps, I thrive on helping clients with platform design, enterprise architecture, and strategic roadmaps.
+
+Talk is cheap, show me the code:
+
+- My Github: https://github.com/MacHu-GWU

{rstobj-1.2.1 → rstobj-2.0.1}/LICENSE.txt

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright 2022 Sanhe Hu <https://github.com/MacHu-GWU/rstobj-project>
+Copyright (c) 2026 Sanhe Hu <husanhe@email.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{rstobj-1.2.1/rstobj.egg-info → rstobj-2.0.1}/PKG-INFO

@@ -1,45 +1,63 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: rstobj
-Version: 1.2.1
-Summary: Construct RestructuredText markup and directives from Python Code.
-Home-page: https://github.com/MacHu-GWU/rstobj-project
-Download-URL: https://pypi.python.org/pypi/rstobj/1.2.1#downloads
-Author: Sanhe Hu
-Author-email: husanhe@gmail.com
-Maintainer: Sanhe Hu
-Maintainer-email: husanhe@gmail.com
-License: MIT
-Platform: Windows
-Platform: MacOS
-Platform: Unix
-Classifier: Development Status :: 5 - Production/Stable
+Version: 2.0.1
+Summary: Construct reStructuredText markup and directives from Python code.
+Author-email: Sanhe Hu <husanhe@gmail.com>
+Maintainer-email: Sanhe Hu <husanhe@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MacHu-GWU/rstobj-project
+Project-URL: Documentation, https://rstobj.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/MacHu-GWU/rstobj-project
+Project-URL: Issues, https://github.com/MacHu-GWU/rstobj-project/issues
+Project-URL: Changelog, https://github.com/MacHu-GWU/rstobj-project/blob/main/release-history.rst
+Project-URL: Download, https://pypi.org/pypi/rstobj#files
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: Unix
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3 :: Only
-Provides-Extra: tests
-Provides-Extra: docs
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <4.0,>=3.11
+Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 License-File: AUTHORS.rst
+Requires-Dist: jinja2<4.0.0,>=3.1.0
+Provides-Extra: dev
+Requires-Dist: rich<15.0.0,>=14.3.4; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest<10.0.0,>=9.1.1; extra == "test"
+Requires-Dist: pytest-cov<8.0.0,>=7.1.0; extra == "test"
+Requires-Dist: docutils<1.0.0,>=0.21.2; extra == "test"
+Provides-Extra: doc
+Requires-Dist: Sphinx<9.0.0,>=8.2.3; extra == "doc"
+Requires-Dist: sphinx-copybutton<1.0.0,>=0.5.2; extra == "doc"
+Requires-Dist: sphinx-design<1.0.0,>=0.7.0; extra == "doc"
+Requires-Dist: sphinx-jinja<3.0.0,>=2.0.2; extra == "doc"
+Requires-Dist: furo==2025.12.19; extra == "doc"
+Requires-Dist: pygments<3.0.0,>=2.18.0; extra == "doc"
+Requires-Dist: ipython<8.19.0,>=8.18.1; extra == "doc"
+Requires-Dist: ipykernel<8.0.0,>=7.3.0; extra == "doc"
+Requires-Dist: nbsphinx<1.0.0,>=0.9.8; extra == "doc"
+Requires-Dist: docfly<4.0.0,>=3.0.3; extra == "doc"
+Provides-Extra: mise
+Requires-Dist: PyGithub<3.0.0,>=2.8.0; extra == "mise"
+Requires-Dist: httpx2<3.0.0,>=2.13.1; extra == "mise"
+Dynamic: license-file
 
 
 .. image:: https://readthedocs.org/projects/rstobj/badge/?version=latest
-    :target: https://rstobj.readthedocs.io/index.html
+    :target: https://rstobj.readthedocs.io/en/latest/
     :alt: Documentation Status
 
-.. image:: https://github.com/MacHu-GWU/rstobj-project/workflows/CI/badge.svg
+.. image:: https://github.com/MacHu-GWU/rstobj-project/actions/workflows/main.yml/badge.svg
     :target: https://github.com/MacHu-GWU/rstobj-project/actions?query=workflow:CI
 
-.. image:: https://codecov.io/gh/MacHu-GWU/rstobj-project/branch/master/graph/badge.svg
+.. image:: https://codecov.io/gh/MacHu-GWU/rstobj-project/branch/main/graph/badge.svg
     :target: https://codecov.io/gh/MacHu-GWU/rstobj-project
 
 .. image:: https://img.shields.io/pypi/v/rstobj.svg
@@ -51,20 +69,16 @@ License-File: AUTHORS.rst
 .. image:: https://img.shields.io/pypi/pyversions/rstobj.svg
     :target: https://pypi.python.org/pypi/rstobj
 
-.. image:: https://img.shields.io/badge/STAR_Me_on_GitHub!--None.svg?style=social
+.. image:: https://img.shields.io/badge/✍️_Release_History!--None.svg?style=social&logo=github
+    :target: https://github.com/MacHu-GWU/rstobj-project/blob/main/release-history.rst
+
+.. image:: https://img.shields.io/badge/⭐_Star_me_on_GitHub!--None.svg?style=social&logo=github
     :target: https://github.com/MacHu-GWU/rstobj-project
 
 ------
 
-
-.. image:: https://img.shields.io/badge/Link-Document-blue.svg
-    :target: https://rstobj.readthedocs.io/index.html
-
 .. image:: https://img.shields.io/badge/Link-API-blue.svg
-    :target: https://rstobj.readthedocs.io/py-modindex.html
-
-.. image:: https://img.shields.io/badge/Link-Source_Code-blue.svg
-    :target: https://rstobj.readthedocs.io/py-modindex.html
+    :target: https://rstobj.readthedocs.io/en/latest/py-modindex.html
 
 .. image:: https://img.shields.io/badge/Link-Install-blue.svg
     :target: `install`_
@@ -84,6 +98,8 @@ License-File: AUTHORS.rst
 
 Welcome to ``rstobj`` Documentation
 ==============================================================================
+.. image:: https://rstobj.readthedocs.io/en/latest/_static/rstobj-logo.png
+    :target: https://rstobj.readthedocs.io/en/latest/
 
 ``rstobj`` is a library that construct Restructured Text markup or directives from Python Code. ``rstobj`` is based on ``jinja2``.
 
@@ -106,23 +122,21 @@ I have a `Blog Post <https://github.com/MacHu-GWU/Tech-Blog/issues/6>`_ to share
 
 .. code-block:: python
 
-    import rstobj # or from rstobj import *
+    import rstobj.api as rstobj
 
     header = rstobj.markup.Header(title="Section1", header_level=1, auto_label=True)
-    rst_header = header.render()
-    print(rst_header)
+    print(header.render())
 
     ltable = rstobj.directives.ListTable(
         data=[["id", "name"], [1, "Alice"], [2, "Bob"]],
         title="Users",
         header=True,
     )
-    rst = ltable.render()
-    print(rst_ltable)
+    print(ltable.render())
 
 Output::
 
-    .. _section1:
+    .. _Section1:
 
     Section1
     ========
@@ -138,7 +152,9 @@ Output::
         * - 2
           - Bob
 
-I recommend to use this in your jinja2 template, content of ``outut.rst``::
+See the `Rendering Gallery <https://rstobj.readthedocs.io/en/latest/01-Rendering-Gallery/index.html>`_ 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() }}
@@ -185,3 +201,16 @@ To upgrade to latest version:
 .. code-block:: console
 
     $ pip install --upgrade rstobj
+
+.. _use-with-ai-coding-agents:
+
+Use with AI Coding Agents
+------------------------------------------------------------------------------
+
+This repo ships an `Agent Skill <https://code.claude.com/docs/en/skills>`_ 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 <https://github.com/MacHu-GWU/rstobj-project/tree/main/.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:
+
+.. code-block:: console
+
+    $ 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/

{rstobj-1.2.1 → rstobj-2.0.1}/README.rst

@@ -1,12 +1,12 @@
 
 .. image:: https://readthedocs.org/projects/rstobj/badge/?version=latest
-    :target: https://rstobj.readthedocs.io/index.html
+    :target: https://rstobj.readthedocs.io/en/latest/
     :alt: Documentation Status
 
-.. image:: https://github.com/MacHu-GWU/rstobj-project/workflows/CI/badge.svg
+.. image:: https://github.com/MacHu-GWU/rstobj-project/actions/workflows/main.yml/badge.svg
     :target: https://github.com/MacHu-GWU/rstobj-project/actions?query=workflow:CI
 
-.. image:: https://codecov.io/gh/MacHu-GWU/rstobj-project/branch/master/graph/badge.svg
+.. image:: https://codecov.io/gh/MacHu-GWU/rstobj-project/branch/main/graph/badge.svg
     :target: https://codecov.io/gh/MacHu-GWU/rstobj-project
 
 .. image:: https://img.shields.io/pypi/v/rstobj.svg
@@ -18,20 +18,16 @@
 .. image:: https://img.shields.io/pypi/pyversions/rstobj.svg
     :target: https://pypi.python.org/pypi/rstobj
 
-.. image:: https://img.shields.io/badge/STAR_Me_on_GitHub!--None.svg?style=social
+.. image:: https://img.shields.io/badge/✍️_Release_History!--None.svg?style=social&logo=github
+    :target: https://github.com/MacHu-GWU/rstobj-project/blob/main/release-history.rst
+
+.. image:: https://img.shields.io/badge/⭐_Star_me_on_GitHub!--None.svg?style=social&logo=github
     :target: https://github.com/MacHu-GWU/rstobj-project
 
 ------
 
-
-.. image:: https://img.shields.io/badge/Link-Document-blue.svg
-    :target: https://rstobj.readthedocs.io/index.html
-
 .. image:: https://img.shields.io/badge/Link-API-blue.svg
-    :target: https://rstobj.readthedocs.io/py-modindex.html
-
-.. image:: https://img.shields.io/badge/Link-Source_Code-blue.svg
-    :target: https://rstobj.readthedocs.io/py-modindex.html
+    :target: https://rstobj.readthedocs.io/en/latest/py-modindex.html
 
 .. image:: https://img.shields.io/badge/Link-Install-blue.svg
     :target: `install`_
@@ -51,6 +47,8 @@
 
 Welcome to ``rstobj`` Documentation
 ==============================================================================
+.. image:: https://rstobj.readthedocs.io/en/latest/_static/rstobj-logo.png
+    :target: https://rstobj.readthedocs.io/en/latest/
 
 ``rstobj`` is a library that construct Restructured Text markup or directives from Python Code. ``rstobj`` is based on ``jinja2``.
 
@@ -73,23 +71,21 @@ I have a `Blog Post <https://github.com/MacHu-GWU/Tech-Blog/issues/6>`_ to share
 
 .. code-block:: python
 
-    import rstobj # or from rstobj import *
+    import rstobj.api as rstobj
 
     header = rstobj.markup.Header(title="Section1", header_level=1, auto_label=True)
-    rst_header = header.render()
-    print(rst_header)
+    print(header.render())
 
     ltable = rstobj.directives.ListTable(
         data=[["id", "name"], [1, "Alice"], [2, "Bob"]],
         title="Users",
         header=True,
     )
-    rst = ltable.render()
-    print(rst_ltable)
+    print(ltable.render())
 
 Output::
 
-    .. _section1:
+    .. _Section1:
 
     Section1
     ========
@@ -105,7 +101,9 @@ Output::
         * - 2
           - Bob
 
-I recommend to use this in your jinja2 template, content of ``outut.rst``::
+See the `Rendering Gallery <https://rstobj.readthedocs.io/en/latest/01-Rendering-Gallery/index.html>`_ 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() }}
@@ -151,4 +149,17 @@ To upgrade to latest version:
 
 .. code-block:: console
 
-    $ pip install --upgrade rstobj
+    $ pip install --upgrade rstobj
+
+.. _use-with-ai-coding-agents:
+
+Use with AI Coding Agents
+------------------------------------------------------------------------------
+
+This repo ships an `Agent Skill <https://code.claude.com/docs/en/skills>`_ 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 <https://github.com/MacHu-GWU/rstobj-project/tree/main/.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:
+
+.. code-block:: console
+
+    $ 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/

rstobj-2.0.1/pyproject.toml

@@ -0,0 +1,131 @@
+# [project] table: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
+[project]
+name = "rstobj"
+# Bump before each release (https://semver.org/), then ``mise run inst`` to update ``uv.lock``.
+version = "2.0.1"
+description = "Construct reStructuredText markup and directives from Python code."
+# An SPDX license expression (PEP 639); keep ``LICENSE.txt`` in sync.
+# Read: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license-and-license-files
+# Valid identifiers: https://spdx.org/licenses/
+license = "MIT"
+license-files = ["LICENSE.txt", "AUTHORS.rst"]
+authors = [
+    { name = "Sanhe Hu", email = "husanhe@gmail.com" },
+]
+maintainers = [
+    { name = "Sanhe Hu", email = "husanhe@gmail.com" },
+]
+keywords = []
+readme = "README.rst"
+requires-python = ">=3.11,<4.0"
+# Read: https://pypi.org/classifiers/
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS",
+    "Operating System :: Unix",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+# --- Dependencies ---
+# Edit these lists, then ``mise run inst`` to update ``uv.lock`` and ``.venv``.
+dependencies = [
+    "jinja2>=3.1.0,<4.0.0", # renders the reST templates in rstobj/templates
+]
+
+# --- Optional dependencies (extras) ---
+# Read: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#dependencies-optional-dependencies
+# Each one must support every Python version in ``requires-python``.
+[project.optional-dependencies]
+
+# local development
+dev = [
+    "rich>=14.3.4,<15.0.0",
+]
+
+# tests and coverage
+test = [
+    "pytest>=9.1.1,<10.0.0",
+    "pytest-cov>=7.1.0,<8.0.0",
+    "docutils>=0.21.2,<1.0.0", # checks that the rendered reST is valid
+]
+
+# docs build
+doc = [
+    "Sphinx>=8.2.3,<9.0.0", # held below 9 until its autodoc rewrite is verified
+    "sphinx-copybutton>=0.5.2,<1.0.0", # copy button on code blocks
+    "sphinx-design>=0.7.0,<1.0.0", # cards, tabs, grids
+    "sphinx-jinja>=2.0.2,<3.0.0", # jinja in reST
+    "furo==2025.12.19", # theme
+    "pygments>=2.18.0,<3.0.0", # syntax highlighting
+    "ipython>=8.18.1,<8.19.0", # notebook execution
+    "ipykernel>=7.3.0,<8.0.0", # notebook kernel
+    "nbsphinx>=0.9.8,<1.0.0", # notebooks as doc pages
+    "docfly>=3.0.3,<4.0.0", # toctree and API reference
+]
+
+# mise tasks
+mise = [
+    "PyGithub>=2.8.0,<3.0.0", # GitHub API client
+    "httpx2>=2.13.1,<3.0.0", # Codecov and Read the Docs APIs
+]
+
+[project.urls]
+Homepage = "https://github.com/MacHu-GWU/rstobj-project"
+Documentation = "https://rstobj.readthedocs.io/en/latest/"
+Repository = "https://github.com/MacHu-GWU/rstobj-project"
+Issues = "https://github.com/MacHu-GWU/rstobj-project/issues"
+Changelog = "https://github.com/MacHu-GWU/rstobj-project/blob/main/release-history.rst"
+Download = "https://pypi.org/pypi/rstobj#files"
+
+# Read: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#creating-executable-scripts
+[project.scripts]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = [
+    "rstobj*",
+]
+exclude = [
+    "rstobj.tests",
+    "rstobj.tests.*",
+    "rstobj.docs",
+    "rstobj.docs.*",
+]
+
+# Non-Python files shipped in the wheel: the jinja2 templates rendered by ``rstobj.templates``.
+[tool.setuptools.package-data]
+rstobj = [
+    "templates/*.rst",
+]
+
+# --- ruff: ``mise run format`` / ``mise run lint`` ---
+[tool.ruff]
+extend-exclude = [
+    "rstobj/vendor",
+    ".claude/skills/*/assets", # templates, not valid Python
+]
+
+[tool.ruff.lint.per-file-ignores]
+# re-export modules
+"**/__init__.py" = ["F401"]
+"**/api.py" = ["F401"]
+
+# --- pytest 9+ native table ---
+# Read: https://docs.pytest.org/en/stable/reference/customize.html#pyproject-toml
+[tool.pytest]
+testpaths = ["tests"]
+# strict = true # only with a pinned pytest
+# filterwarnings = ["error"]
+# markers = ["slow: tests that take more than a few seconds"]
+
+# --- Build (``mise run build``); setuptools 77+ for PEP 639 ``license`` ---
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"

rstobj-2.0.1/rstobj/__init__.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+
+"""
+Construct RestructuredText markup and directives from Python Code.
+"""

rstobj-2.0.1/rstobj/api.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+from .directives import api as directives
+from .markup import api as markup

rstobj-2.0.1/rstobj/base.py

@@ -0,0 +1,139 @@
+# -*- coding: utf-8 -*-
+
+"""
+RestructuredText Object abstraction.
+"""
+
+from __future__ import annotations
+
+import typing as T
+from dataclasses import dataclass
+
+if T.TYPE_CHECKING:  # pragma: no cover
+    from jinja2 import Template
+
+from .templates import env
+from .option import Options
+
+
+def _indent_line(line: str, prefix: str) -> str:
+    """
+    Prefix a line and strip its trailing whitespace. A blank line stays empty,
+    so indenting never leaves whitespace-only lines.
+    """
+    line = line.rstrip()
+    if line:
+        return prefix + line
+    else:
+        return ""
+
+
+def _indent_continuation(text: str, width: int, force: bool) -> str:
+    """
+    Indent every line after the first by ``width`` spaces, so a multi-line
+    text stays inside the list item or table cell it starts in.
+
+    :param force: if False, text whose continuation lines are all indented by
+        at least ``width`` already is returned unchanged, so callers that
+        indented their strings by hand keep the same output.
+    """
+    lines = text.split("\n")
+    rest = lines[1:]
+    if not force:
+        is_indented = all(
+            (not line.strip()) or (len(line) - len(line.lstrip(" ")) >= width)
+            for line in rest
+        )
+        if is_indented:
+            return text
+    prefix = " " * width
+    return "\n".join([lines[0]] + [_indent_line(line, prefix) for line in rest])
+
+
+@dataclass(kw_only=True)
+class RstObj:
+    """
+    The base restructured text object.
+    """
+
+    @property
+    def template_name(self) -> str:
+        """
+        Find template file.
+        """
+        return "{}.{}.rst".format(self.__module__, self.__class__.__name__)
+
+    @property
+    def template(self) -> Template:
+        """
+        Return ``jinja2.Template`` instance.
+        """
+        return env.get_template(self.template_name)
+
+    def render(
+        self,
+        indent: int | None = None,
+        first_line_indent: int | None = None,
+        **kwargs,
+    ) -> str:
+        """
+        Render this object into text.
+
+        :param indent: global indent. Indent length can be changed in
+            :attr:`rstobj.option.Options.tab`.
+
+        :param first_line_indent: sometimes we only need to indent
+            first line, this option will overwrite the ``indent`` argument.
+
+        :param kwargs: other optional arguments.
+        """
+        out = self.template.render(obj=self, tab=Options.tab)
+        if indent or first_line_indent:
+            origin_lines = out.split("\n")
+            target_lines = [
+                _indent_line(line, Options.tab * (indent or 0)) for line in origin_lines
+            ]
+            if first_line_indent is not None:
+                if first_line_indent >= 0:
+                    target_lines[0] = _indent_line(
+                        origin_lines[0],
+                        Options.tab * first_line_indent,
+                    )
+                else:  # pragma: no cover
+                    raise TypeError
+            out = "\n".join(target_lines)
+        return out
+
+    @staticmethod
+    def str_or_render(
+        value: str | RstObj,
+        **kwargs,
+    ) -> str:
+        """
+        If it is a string type, then just return. If it is a RstObj type,
+        then return the rendered string.
+        """
+        if isinstance(value, RstObj):
+            return value.render(**kwargs)
+        else:
+            return str(value)
+
+    @staticmethod
+    def _render_nested(
+        value: str | RstObj,
+        width: int,
+    ) -> str:
+        """
+        Render a list item or table cell whose text starts after a marker
+        ``width`` characters wide, such as ``"- "`` or ``"    * - "``.
+
+        A :class:`RstObj` is rendered without its leading and trailing blank
+        lines, and all its continuation lines are indented. A string is taken
+        as reStructuredText; its continuation lines are indented unless they
+        already are.
+        """
+        if isinstance(value, RstObj):
+            text = value.render().strip("\n")
+            return _indent_continuation(text, width, force=True)
+        else:
+            return _indent_continuation(str(value), width, force=False)

rstobj-2.0.1/rstobj/directives/__init__.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+
+"""
+reStructuredText Directives: http://docutils.sourceforge.net/docs/ref/rst/directives.html
+"""

rstobj-2.0.1/rstobj/directives/api.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+
+from .image import Image
+from .table import ListTable
+from .codeblock import Code
+from .codeblock import CodeBlockEmpty
+from .codeblock import CodeBlockBase
+from .codeblock import CodeBlock
+from .codeblock import CodeBlockPython
+from .codeblock import CodeBlockRuby
+from .codeblock import CodeBlockR
+from .codeblock import CodeBlockPerl
+from .codeblock import CodeBlockC
+from .codeblock import CodeBlockCPP
+from .codeblock import CodeBlockHTML
+from .codeblock import CodeBlockCSS
+from .codeblock import CodeBlockJavaScript
+from .codeblock import CodeBlockSQL
+from .codeblock import CodeBlockScala
+from .codeblock import CodeBlockMake
+from .codeblock import CodeBlockBash
+from .codeblock import CodeBlockLua
+from .codeblock import CodeBlockRst
+from .codeblock import CodeBlockMarkdown
+from .toc import TableOfContent
+from .miscellaneous import Include

rstobj-2.0.1/rstobj/directives/base.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+import typing as T
+from dataclasses import dataclass
+from dataclasses import field
+from ..base import RstObj
+
+
+@dataclass(kw_only=True)
+class Directive(RstObj):
+    class_: str | None = field(default=None)
+    name: str | None = field(default=None)
+
+    meta_directive_keyword: T.ClassVar[str | None] = None
+    #: False for a directive that has no ``:name:`` option, such as ``contents``.
+    meta_supports_name: T.ClassVar[bool] = True
+
+    @property
+    def arg(self):  # pragma: no cover
+        raise NotImplementedError