sphinxnotes-recentupdate 1.0__py3-none-any.whl

sphinxnotes/recentupdate/__init__.py

@@ -0,0 +1,276 @@
+"""
+sphinxnotes.recentupdate
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Get the document update information from git and display it in Sphinx documentation.
+
+:copyright: Copyright 2021 Shengyu Zhang
+:license: BSD, see LICENSE for details.
+"""
+
+from __future__ import annotations
+from typing import Iterable, TYPE_CHECKING
+from textwrap import dedent
+from datetime import datetime
+from dataclasses import dataclass
+from os import path
+from pathlib import Path
+
+from docutils import nodes
+from docutils.statemachine import StringList
+from docutils.parsers.rst import directives
+
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import nested_parse_with_titles
+from sphinx.util.matching import Matcher
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+from git import Repo
+import jinja2
+
+from . import meta
+
+
+logger = logging.getLogger(__name__)
+
+
+class Environment(jinja2.Environment):
+    datefmt: str
+
+    def __init__(self, datefmt: str, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.datefmt = datefmt
+        self.filters['strftime'] = self._strftime_filter
+        self.filters['roles'] = self._roles_filter
+
+    def _strftime_filter(self, value, format=None) -> str:
+        """
+        Filter for stringify datetime given format.
+        if no format given, use confval "recentupdate_date_format".
+        """
+        if format is None:
+            format = self.datefmt
+        return value.strftime(format)
+
+    def _roles_filter(self, value: Iterable[str], role: str) -> Iterable[str]:
+        """
+        A heplfer filter for converting list of string to list of role.
+
+        For example::
+
+            {{ ["foo", "bar"] | roles("doc") }}
+
+        Produces ``[":doc:`foo`", ":doc:`bar`"]``.
+        """
+        return map(lambda x: ':%s:`%s`' % (role, x), value)
+
+
+@dataclass
+class Revision(object):
+    """
+    Revision represents a git commit which contains document changes.
+    """
+
+    #: Git commit message
+    message: str
+    #: Git commit author
+    author: str
+    #: Git commit author date
+    date: datetime
+
+    # FYI, possible status letters are:
+    # :A: addition of a file
+    # :C: copy of a file into a new one
+    # :D: deletion of a file
+    # :M: modification of the contents or mode of a file
+    # :R: renaming of a file
+    # :T: change in the type of the file
+    # :U: file is unmerged (you must complete the merge before it can be committed)
+    # :X: "unknown" change type (most probably a bug, please report it)
+
+    #: List of docname, corresponding to files which are modified
+    addition: list[str]
+    #: List of docname, corresponding to files which are newly added
+    modification: list[str]
+    #: List of docname, corresponding to files which are deleted
+    deletion: list[str]
+
+
+class RecentUpdateDirective(SphinxDirective):
+    """Directive for displaying recent update."""
+
+    # Member of parent
+    has_content: bool = True
+    required_arguments: int = 0
+    optional_arguments: int = 1
+    final_argument_whitespace: bool = False
+    option_spec = {}
+
+    #: Repo info
+    repo: Repo = None
+
+    def _get_docname(self, relfn_to_repo: str) -> str | None:
+        relsrcdir_to_repo = path.relpath(self.env.srcdir, self.repo.working_dir)
+        relfn_to_srcdir = path.relpath(relfn_to_repo, relsrcdir_to_repo)
+        absfn = path.abspath(relfn_to_srcdir)
+        if Path(path.commonpath([self.env.srcdir, absfn])) != self.env.srcdir:
+            logger.debug(f'Skip {relfn_to_repo}: out of srcdir')
+            return None
+
+        excluded = Matcher(self.config.exclude_patterns)
+        if excluded(relfn_to_srcdir):
+            logger.debug(f'Skip {relfn_to_repo}: excluded by exclude_patterns confval')
+            return None
+
+        docname, ext = path.splitext(relfn_to_srcdir)
+        source_suffix = list(self.config.source_suffix.keys())
+        if not ext or ext not in source_suffix:
+            logger.debug(f'Skip {relfn_to_repo}: not {source_suffix} files')
+            return None
+
+        for p in self.config.recentupdate_exclude_path:
+            absp = path.abspath(p)
+            if path.commonpath([absp, absfn]) == absp:
+                logger.debug(
+                    f'Skip {relfn_to_repo}: excluded by recentupdate_exclude_path confval'
+                )
+                return None
+
+        logger.debug(f'Get docname: {docname}')
+        return docname
+
+    def _context(self, count: int) -> dict[str, any]:
+        revisions = []
+        res = {'revisions': revisions}
+
+        cur = self.repo.head.commit
+        if cur is None:
+            return res
+
+        # Get recent N commits which contain document changes (N = count)
+        n = 0
+        while n < count:
+            prev = cur.parents[0] if len(cur.parents) != 0 else None
+            if prev is None:
+                break
+
+            matches = [
+                x in cur.message for x in self.config.recentupdate_exclude_commit
+            ]
+            if any(matches):
+                logger.debug(
+                    f'Skip commit {cur.hexsha}: excluded by recentupdate_exclude_commit confval'
+                )
+                cur = prev
+                continue
+
+            m = []
+            a = []
+            d = []
+            diff_idx = prev.tree.diff(cur)
+            for diff in diff_idx:
+                docname = self._get_docname(diff.a_path)
+                if docname is None:
+                    # Skip files out of srcdir
+                    continue
+
+                if diff.change_type == 'M':
+                    m.append(docname)
+                elif diff.change_type == 'A':
+                    a.append(docname)
+                elif diff.change_type == 'D':
+                    d.append(docname)
+                else:
+                    logger.warning(
+                        f'Skip {diff.a_path}: unsupport change type {diff.change_type}'
+                    )
+
+            if len(m) + len(a) + len(d) == 0:
+                # Dont create revisions when no document changes
+                logger.debug(f'Skip commit {cur.hexsha}: no document changes')
+                cur = prev
+                continue
+
+            revisions.append(
+                Revision(
+                    message=cur.message,
+                    author=cur.author,
+                    date=datetime.utcfromtimestamp(cur.authored_date),
+                    modification=m,
+                    addition=a,
+                    deletion=d,
+                )
+            )
+            cur = prev
+            n += 1
+
+        logger.warning(
+            f'[recentupdate] Intend to get recent {count} commits, eventually get {n}'
+        )
+
+        return res
+
+    def run(self) -> list[nodes.Node]:
+        if len(self.arguments) >= 1:
+            count = directives.nonnegative_int(self.arguments[0])
+        else:
+            count = self.config.recentupdate_count
+
+        # Render reST from Jinja template, then parse it in to document
+        env = Environment(self.config.recentupdate_date_format)
+
+        try:
+            template = env.from_string(
+                '\n'.join(list(self.content)) or self.config.recentupdate_template
+            )
+            lines = template.render(self._context(count)).split('\n')
+        except Exception as e:
+            msg = f'failed to render recentupdate template: {e}'
+            logger.warning(msg, location=self.state.parent)
+            sm = nodes.system_message(
+                msg, type='WARNING', level=2, backrefs=[], source=''
+            )
+            return [sm]
+        else:
+            nested_parse_with_titles(self.state, StringList(lines), self.state.parent)
+            return []
+
+
+DEFAULT_TEMPLATE = dedent("""
+                          {% 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 %}
+                          """)
+
+
+def setup(app: Sphinx):
+    """Sphinx extension entrypoint."""
+    meta.pre_setup(app)
+
+    # Set current git repo
+    RecentUpdateDirective.repo = Repo(app.srcdir, search_parent_directories=True)
+
+    app.add_directive('recentupdate', RecentUpdateDirective)
+
+    app.add_config_value('recentupdate_count', 10, 'env')
+    app.add_config_value('recentupdate_template', DEFAULT_TEMPLATE, 'env')
+    app.add_config_value('recentupdate_date_format', '%Y-%m-%d', 'env')
+    app.add_config_value('recentupdate_exclude_path', [], 'env')
+    app.add_config_value('recentupdate_exclude_commit', ['skip-recentupdate'], 'env')
+
+    return meta.post_setup(app)

sphinxnotes/recentupdate/meta.py

@@ -0,0 +1,35 @@
+# This file is generated from sphinx-notes/cookiecutter.
+# DO NOT EDIT!!!
+
+################################################################################
+# Project meta infos.
+################################################################################
+
+from __future__ import annotations
+from importlib import metadata
+
+__project__ = 'sphinxnotes-recentupdate'
+__author__ = 'Shengyu Zhang'
+__desc__ = 'Get the document update information from git and display it in Sphinx documentation'
+
+try:
+    __version__ = metadata.version('sphinxnotes-recentupdate')
+except metadata.PackageNotFoundError:
+    __version__ = 'unknown'
+
+
+################################################################################
+# Sphinx extension utils.
+################################################################################
+
+
+def pre_setup(app):
+    app.require_sphinx('7.0')
+
+
+def post_setup(app):
+    return {
+        'version': __version__,
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

sphinxnotes_recentupdate-1.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: sphinxnotes-recentupdate
+Version: 1.0
+Summary: Get the document update information from git and display it in Sphinx documentation
+Author: Shengyu Zhang
+Maintainer: Shengyu Zhang
+License-Expression: BSD-3-Clause
+Project-URL: homepage, https://sphinx.silverrainz.me/recentupdate
+Project-URL: documentation, https://sphinx.silverrainz.me/recentupdate
+Project-URL: repository, https://github.com/sphinx-notes/recentupdate
+Project-URL: changelog, https://sphinx.silverrainz.me/recentupdate/changelog.html
+Project-URL: tracker, https://github.com/sphinx-notes/recentupdate/issues
+Keywords: sphinx,extension,documentation,sphinxnotes
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Plugins
+Classifier: Framework :: Sphinx
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Documentation :: Sphinx
+Requires-Python: >=3.12
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: Sphinx>=7.0
+Requires-Dist: GitPython
+Requires-Dist: Jinja2
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: cruft; extra == "dev"
+Requires-Dist: ruff>=0.11.10; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: docs
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: sphinx_design; extra == "docs"
+Requires-Dist: sphinx_copybutton; extra == "docs"
+Requires-Dist: sphinxcontrib-gtagjs; extra == "docs"
+Requires-Dist: sphinx-sitemap; extra == "docs"
+Requires-Dist: sphinxext-opengraph; extra == "docs"
+Requires-Dist: sphinx-last-updated-by-git; extra == "docs"
+Requires-Dist: sphinxnotes-project; extra == "docs"
+Requires-Dist: sphinxnotes-comboroles; extra == "docs"
+Dynamic: license-file
+
+.. This file is generated from sphinx-notes/cookiecutter.
+   You need to consider modifying the TEMPLATE or modifying THIS FILE.
+
+========================
+sphinxnotes-recentupdate
+========================
+
+.. |docs| image:: https://img.shields.io/github/deployments/sphinx-notes/recentupdate/github-pages
+   :target: https://sphinx.silverrainz.me/recentupdate
+   :alt: Documentation Status
+.. |license| image:: https://img.shields.io/github/license/sphinx-notes/recentupdate
+   :target: https://github.com/sphinx-notes/recentupdate/blob/master/LICENSE
+   :alt: Open Source License
+.. |pypi| image:: https://img.shields.io/pypi/v/sphinxnotes-recentupdate.svg
+   :target: https://pypi.python.org/pypi/sphinxnotes-recentupdate
+   :alt: PyPI Package
+.. |download| image:: https://img.shields.io/pypi/dm/sphinxnotes-recentupdate
+   :target: https://pypi.python.org/pypi/sphinxnotes-recentupdate
+   :alt: PyPI Package Downloads
+
+|docs| |license| |pypi| |download|
+
+Get the document update information from git and display it in Sphinx documentation.
+
+.. INTRODUCTION START 
+   (MUST written in standard reStructuredText, without Sphinx stuff)
+
+.. INTRODUCTION END
+
+Please refer to Documentation_ for more details.
+
+.. _Documentation: https://sphinx.silverrainz.me/recentupdate

sphinxnotes_recentupdate-1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+sphinxnotes/recentupdate/__init__.py,sha256=32kX_x5XyvY4HERoJpMscl-UtAq-VsLDuT42Rh_neDE,9148
+sphinxnotes/recentupdate/meta.py,sha256=Spl5MmwH1Nthcm-wbW2UzZnqrfKdLiOmfa2V2sEKHTw,1018
+sphinxnotes/recentupdate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sphinxnotes_recentupdate-1.0.dist-info/licenses/LICENSE,sha256=Sa0uIqyOtooTO3N9W29mvi1uHW1uL0lmU7oRYumv8sA,1520
+sphinxnotes_recentupdate-1.0.dist-info/METADATA,sha256=85RSHYtjoOWqufu258MPNf3ipcKinOztoy78VYK2hYE,3231
+sphinxnotes_recentupdate-1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sphinxnotes_recentupdate-1.0.dist-info/top_level.txt,sha256=V-VWtuPpvntuonwz7_KceUnT4-CbPR1gJ26BTFpvcJI,12
+sphinxnotes_recentupdate-1.0.dist-info/RECORD,,

sphinxnotes_recentupdate-1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sphinxnotes_recentupdate-1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Shengyu Zhang
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sphinxnotes_recentupdate-1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sphinxnotes