sphinxnotes-render¶

Introduction¶

This extension mainly consists of two parts:

sphinxnotes.render: A framework to define, constrain, and render data in Sphinx documentation.
sphinxnotes.render.ext: An extension built on top of this framework, allowing user to define, constrain and render data entirely through the markup language.

Getting Started¶

Note

In this section we discuss how to use the sphinxnotes.render.ext extension. For the document to write your own extension, please refer to Extending.

Note

We assume you already have a Sphinx documentation, if not, see Getting Started with Sphinx.

First, downloading extension from PyPI:

$ pip install "sphinxnotes-render[ext]"

Then, add the extension name to extensions configuration item in your conf.py:

extensions = [
          # …
          'sphinxnotes.render.ext',
          # …
          ]

We need to create a template to tell extension how to render the data. The extension provides two ways for this:

Way 1: by Directive¶

The data.template directive will not change the content document, it creates and stashes a temporary template for later use:

.. data.template::

   Hi human! I am a cat named {{ name }}, I have {{ color }} fur.

   {{ content }}.

Now we can define data, using a data.define directive:

Source

.. data.define:: mimi
   :color: black and brown

   I like fish!

Result

Hi human! I am a cat named mimi, I have black and brown fur.

I like fish!.

Please refer to Directives for more details.

Way 2: by Configuration¶

Add the following code to your conf.py:

render_ext_data_define_directives = {
   'cat': {
       'schema': {
           'name': 'str, required',
           'attrs': {
               'color': 'str',
           },
           'content': 'str, required'
       },
       'template': {
           'text': '\n'.join([
               'Hi human! I am a cat named {{ name }}, I have {{ color }} fur.',
               '',
               '{{ content }}.',
           ]),
       },
   },
}

This creates a .. cat:: directive that requires a name argument and accepts a color option and a content block. Use it in your document:

Source

.. cat:: mimi
   :color: black and brown

   I like fish!

Result

Hi human! I am a cat named mimi, I have black and brown fur.

I like fish!.

Please refer to render_ext_data_define_directives for more details.

Contents¶

Contents

Change Log

Extension

Framework

The Sphinx Notes Project¶

The project is developed by Shengyu Zhang, as part of The Sphinx Notes Project.

The Sphinx Notes Project