refactor: Migrate to sphinxnotes-render

docs/changelog.rst

@@ -18,6 +18,17 @@ Change Log
 
    Change log here.
 
+Version 2.x
+===========
+
+.. version:: 2.0
+   :break:
+
+   - Integrated with :external+render:doc:`sphinxnotes-render <index>`
+   - Drop the ``.. recentupdate::`` directive, use ``load_extra('recentupdate')``
+     in :rst:dir:`data.render`'s template
+   - Drop the ``recentupdate_date_format`` confval
+
 Version 1.x
 ===========
 

docs/conf.py

@@ -126,3 +126,7 @@
 extensions.append('sphinxnotes.recentupdate')
 
 # CUSTOM CONFIGURATION
+
+intersphinx_mapping['render'] = ('https://sphinx.silverrainz.me/render', None)
+
+extensions.append('sphinxnotes.render.ext')

docs/conf.rst

@@ -4,53 +4,10 @@ Configuration
 
 The extension provides the following configuration:
 
-.. confval:: recentupdate_count
-   :type: int
-   :default: 10
+.. autoconfval:: recentupdate_exclude_path
 
-   The default count of recent revisions. See :doc:`usage`.
+   A list of path that should be excluded when looking for file changes.
 
-.. confval:: recentupdate_template
-   :type: str
-   :default: see below
-
-   The default Jinja template of update information. See :doc:`usage`.
-
-   Here is the default value:
-
-   .. code:: jinja
-
-      {% for r in revisions %}
-      {{ r.date | strftime }}
-        :Author: {{ r.author }}
-        :Message: {{ r.message }}
-
-        {% if r.modification %}
-        - Modified {{ r.modification | roles("doc") | join(", ") }}
-        {% endif %}
-        {% if r.addition %}
-        - Added {{ r.addition | roles("doc") | join(", ") }}
-        {% endif %}
-        {% if r.deletion %}
-        - Deleted {{ r.deletion | join(", ") }}
-        {% endif %}
-      {% endfor %}
-
-.. confval:: recentupdate_date_format
-   :type: str
-   :default: "%Y-%m-%dT"
-
-   The default date format of :ref:`strftime` filter.
-
-.. confval:: recentupdate_exclude_path
-   :type: List[str]
-   :default: []
-
-   A list of path that should be excluded when looking for file changes. 
-
-.. confval:: recentupdate_exclude_commit
-   :type: List[str]
-   :default: ["skip-recentupdate"]
-
-   A list of commit message pattern that should be excluded when looking for file changes. 
+.. autoconfval:: recentupdate_exclude_commit
 
+   A list of commit message pattern that should be excluded when looking for file changes.

docs/index.rst

@@ -27,12 +27,14 @@ Introduction
 
 .. INTRODUCTION START
 
-Get the document update information from git and display it in Sphinx documentation.
+Get the Sphinx document update information from Git repository.
 
-This extensions provides a :doc:`recentupdate <usage>` directive, which can show recent document update of current Sphinx documentation. The update information is read from Git_ repository (So you must use Git to manage your documentation). You can customize the update information through generating reStructuredText from Jinja_ template.
+This extension integrates with :external+render:doc:`sphinxnotes-render <index>`
+by providing an extra context ``recentupdate``. The recent document update
+information is read from a Git_ repository. You can customize the presentation
+via ``data.render`` template.
 
 .. _Git: https://git-scm.com/
-.. _Jinja: https://jinja.palletsprojects.com/en/3.0.x/templates/
 
 .. INTRODUCTION END
 
@@ -58,22 +60,33 @@ Then, add the extension name to ``extensions`` configuration item in your
 .. code-block:: python
 
    extensions = [
-             # …
-             'sphinxnotes.recentupdate',
-             # …
-             ]
+              # …
+              'sphinxnotes.render.ext',
+              'sphinxnotes.recentupdate',
+              # …
+              ]
 
 .. _Getting Started with Sphinx: https://www.sphinx-doc.org/en/master/usage/quickstart.html
 .. _conf.py: https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 .. ADDITIONAL CONTENT START
 
-Add ``recentupdate`` directive to your document, build your document, the directive will be rendered to:
+Now you can use the :rst:dir:`data.render` directive (provided by
+``sphinxnotes.render.ext``) with ``recentupdate`` extra context to render
+a revision list:
 
 .. example::
-   :style: grid
 
-   .. recentupdate::
+   .. data.render::
+
+      The most recent 3 commits:
+
+      {% for r in load_extra('recentupdate', 3) %}
+      ``{{ r.date }}``
+         {{ r.message[0] }}
+      {% endfor %}
+
+Please refer to :doc:`usage` for more details.
 
 .. ADDITIONAL CONTENT END
 

docs/requirements.txt

@@ -12,4 +12,5 @@ sphinxnotes-project
 sphinxnotes-comboroles
 
 # CUSTOM DOCS DEPENDENCIES START
+sphinxnotes-render
 # CUSTOM DOCS DEPENDENCIES END

docs/usage.rst

@@ -2,64 +2,63 @@
 Usage
 =====
 
-The extension provides a ``recentupdate`` directive:
+The extension provides an extra context ``recentupdate`` usable via
+:external+render:term:`load_extra` function in ``sphinxnotes-render`` template:
 
-.. code:: rst
+.. example::
 
-   .. recentupdate:: [count]
+   .. data.render::
 
-      [jinja template]
+      {% for r in load_extra('recentupdate', 3) %}
+      ``📅 {{ r.date }}`` | ``👤{{ r.author }}``
 
-count
-   The optional argument of directive is the count of recent "revisions" you want to show. Revision is a git commit which contains document changes.
+        {{ r.message[0] }}
 
-   If no count given, value of :confval:`recentupdate_count` is used.
+      {% if r.changed_docs %}
+      - Modified {{ r.changed_docs | roles("doc") | join(", ") }}
+      {% endif %}
+      {% if r.added_docs %}
+      - Added {{ r.added_docs | roles("doc") | join(", ") }}
+      {% endif %}
+      {% if r.removed_docs %}
+      - Deleted {{ r.removed_docs | join(", ") }}
+      {% endif %}
 
-template
-   The optional content of directive is a jinja template for generating reStructuredText, in the template you can access Variables_ named `{{ revisions }}`_.
+      {% endfor %}
 
-   Beside, You can use `Builtin Filters`_ and Filters_ provided by extensions.
+The ``load_extra('recentupdate', count=3)`` returns a list of
+:py:class:`~sphinxnotes.recentupdate.Revision` objects from recent Git
+commits that touched document files, see below.
 
-   If no template given, value of :confval:`recentupdate_template` is used.
+The :external+render:term:`roles` filter is provided by ``sphinxnotes-render``
+too.
 
-.. _Builtin Filters: https://jinja.palletsprojects.com/en/3.0.x/templates/#builtin-filters
+.. seealso::
 
-Variables
-=========
+   :external+render:doc:`sphinxnotes-render: Templating <tmpl>`
+     How to write ``data.render`` templates.
+   :external+render:doc:`sphinxnotes-render: Templating <ext>`
+     How extra context and filters work.
 
-All available variables_:
+The "recentupdate" extra context
+=================================
 
-.. _variables: https://jinja.palletsprojects.com/en/3.0.x/templates/#variables
+``load_extra('recentupdate', count=3)`` returns a list of
+:py:class:`~sphinxnotes.recentupdate.Revision` objects from recent Git
+commits that touched document files.
 
-{{ revisions }}
----------------
+- ``count`` (*int*) — Number of recent revisions to return (default ``10``).
 
-``{{ revisions }}`` is an an array of revisions. The length of array is determined by the argument of ``recentupdate`` directive.
+.. py:class:: sphinxnotes.recentupdate.Revision
 
-Here is the schema of array element:
+   .. autoattribute:: message
 
-.. autoclass:: recentupdate.Revision
-   :members:
+   .. autoattribute:: author
 
-Filters
-=======
+   .. autoattribute:: date
 
-.. _strftime:
+   .. autoattribute:: added_docs
 
-strftime
---------
+   .. autoattribute:: changed_docs
 
-Convert a :py:class:`datetime.datetime` to string in given format.
-
-If no format given, use value of :confval:`recentupdate_date_format`.
-
-It is used in :confval:`default template <recentupdate_template>`.
-
-roles
------
-
-Convert a list of string to list of reStructuredText roles.
-
-``{{ ['foo', 'bar'] | roles("doc") }}`` produces ``[':doc:`foo`', ':doc:`bar`']``.
-
-It is used in :confval:`default template <recentupdate_template>`.
+   .. autoattribute:: removed_docs

pyproject.toml

@@ -43,7 +43,7 @@ dependencies = [
 
     # CUSTOM DEPENDENCIES START
     "GitPython",
-    "Jinja2",
+    "sphinxnotes-render",
     # CUSTOM DEPENDENCIES END
 ]