Metadata-Version: 2.4
Name: rstobj
Version: 2.0.0
Summary: An example project generated by cookiecutter-pywf_open_source.
Author-email: Sanhe Hu <husanhe@email.com>
Maintainer-email: Sanhe Hu <husanhe@email.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: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: Unix
Requires-Python: <4.0,>=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
License-File: AUTHORS.rst
Requires-Dist: jinja2
Provides-Extra: dev
Requires-Dist: rich<14.0.0,>=13.8.1; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest<9.0.0,>=8.2.2; extra == "test"
Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == "test"
Provides-Extra: doc
Requires-Dist: Sphinx<8.0.0,>=7.4.7; extra == "doc"
Requires-Dist: sphinx-copybutton<1.0.0,>=0.5.2; extra == "doc"
Requires-Dist: sphinx-design<1.0.0,>=0.6.1; extra == "doc"
Requires-Dist: sphinx-jinja<3.0.0,>=2.0.2; extra == "doc"
Requires-Dist: furo==2024.8.6; 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: nbsphinx<1.0.0,>=0.8.12; extra == "doc"
Requires-Dist: docfly==3.0.1; extra == "doc"
Provides-Extra: mise
Requires-Dist: PyGithub<3.0.0,>=2.8.0; extra == "mise"
Requires-Dist: httpx<1.0.0,>=0.28.0; extra == "mise"
Requires-Dist: tomli<3.0.0,>=2.0.0; python_version < "3.11" and extra == "mise"
Dynamic: license-file


.. image:: https://readthedocs.org/projects/rstobj/badge/?version=latest
    :target: https://rstobj.readthedocs.io/en/latest/
    :alt: Documentation Status

.. 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/main/graph/badge.svg
    :target: https://codecov.io/gh/MacHu-GWU/rstobj-project

.. image:: https://img.shields.io/pypi/v/rstobj.svg
    :target: https://pypi.python.org/pypi/rstobj

.. image:: https://img.shields.io/pypi/l/rstobj.svg
    :target: https://pypi.python.org/pypi/rstobj

.. image:: https://img.shields.io/pypi/pyversions/rstobj.svg
    :target: https://pypi.python.org/pypi/rstobj

.. 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-API-blue.svg
    :target: https://rstobj.readthedocs.io/en/latest/py-modindex.html

.. image:: https://img.shields.io/badge/Link-Install-blue.svg
    :target: `install`_

.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg
    :target: https://github.com/MacHu-GWU/rstobj-project

.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg
    :target: https://github.com/MacHu-GWU/rstobj-project/issues

.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg
    :target: https://github.com/MacHu-GWU/rstobj-project/issues

.. image:: https://img.shields.io/badge/Link-Download-blue.svg
    :target: https://pypi.org/pypi/rstobj#files


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``.

**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 <http://www.sphinx-doc.org/en/master/>`_ 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 <https://github.com/MacHu-GWU/Tech-Blog/issues/6>`_ to share how to create a sphinx doc extension in 50 lines and customize your own directive (Sorry, its written in Chinese).


**Example**:

.. code-block:: python

    import rstobj # or from rstobj import *

    header = rstobj.markup.Header(title="Section1", header_level=1, auto_label=True)
    rst_header = header.render()
    print(rst_header)

    ltable = rstobj.directives.ListTable(
        data=[["id", "name"], [1, "Alice"], [2, "Bob"]],
        title="Users",
        header=True,
    )
    rst = ltable.render()
    print(rst_ltable)

Output::

    .. _section1:

    Section1
    ========

    .. list-table:: Users
        :header-rows: 1
        :stub-columns: 0

        * - id
          - name
        * - 1
          - Alice
        * - 2
          - Bob

I recommend to use this in your jinja2 template, content of ``outut.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:

Install
------------------------------------------------------------------------------

``rstobj`` is released on PyPI, so all you need is:

.. code-block:: console

    $ pip install rstobj

To upgrade to latest version:

.. code-block:: console

    $ pip install --upgrade rstobj
