From 23972d2dff01dd4cda612491478d59659747291d Mon Sep 17 00:00:00 2001 From: su-fang Date: Thu, 2 Feb 2023 17:11:46 +0800 Subject: [PATCH] Import Upstream version 1.0.1 --- CHANGES.rst | 20 +++ LICENSE.rst | 28 ++++ MANIFEST.in | 1 + PKG-INFO | 48 +++++++ README.rst | 29 ++++ setup.cfg | 51 +++++++ setup.py | 4 + src/sphinxcontrib/__init__.py | 1 + src/sphinxcontrib/log_cabinet.py | 132 ++++++++++++++++++ .../PKG-INFO | 48 +++++++ .../SOURCES.txt | 14 ++ .../dependency_links.txt | 1 + .../namespace_packages.txt | 1 + .../requires.txt | 1 + .../top_level.txt | 1 + 15 files changed, 380 insertions(+) create mode 100644 CHANGES.rst create mode 100644 LICENSE.rst create mode 100644 MANIFEST.in create mode 100644 PKG-INFO create mode 100644 README.rst create mode 100644 setup.cfg create mode 100755 setup.py create mode 100644 src/sphinxcontrib/__init__.py create mode 100644 src/sphinxcontrib/log_cabinet.py create mode 100644 src/sphinxcontrib_log_cabinet.egg-info/PKG-INFO create mode 100644 src/sphinxcontrib_log_cabinet.egg-info/SOURCES.txt create mode 100644 src/sphinxcontrib_log_cabinet.egg-info/dependency_links.txt create mode 100644 src/sphinxcontrib_log_cabinet.egg-info/namespace_packages.txt create mode 100644 src/sphinxcontrib_log_cabinet.egg-info/requires.txt create mode 100644 src/sphinxcontrib_log_cabinet.egg-info/top_level.txt diff --git a/CHANGES.rst b/CHANGES.rst new file mode 100644 index 0000000..f2a4086 --- /dev/null +++ b/CHANGES.rst @@ -0,0 +1,20 @@ +1.0.1 +----- + +Released 2019-07-05 + +- Fix old-style class issue in Python 2. :pr:`1` +- Account for a ".x" suffix on the project version. "1.1.x" will + be seen as "1.1" for hiding old log entries. :pr:`5` +- Fix error when log entries are at the very top of a page before any + other content. :issue:`3` +- Config is prefixed with ``log_cabinet_`` instead of ``changelog_``. + The old names are deprecated. :pr:`7` + + +1.0.0 +----- + +Released 2017-05-05 + +- Initial release diff --git a/LICENSE.rst b/LICENSE.rst new file mode 100644 index 0000000..dd372a7 --- /dev/null +++ b/LICENSE.rst @@ -0,0 +1,28 @@ +Copyright 2017 David Lord + +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. diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..7539083 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1 @@ +include CHANGES.rst diff --git a/PKG-INFO b/PKG-INFO new file mode 100644 index 0000000..1065154 --- /dev/null +++ b/PKG-INFO @@ -0,0 +1,48 @@ +Metadata-Version: 1.1 +Name: sphinxcontrib-log-cabinet +Version: 1.0.1 +Summary: Organize changelog directives in Sphinx docs. +Home-page: https://github.com/davidism/sphinxcontrib-log-cabinet +Author: David Lord +Author-email: davidism@gmail.com +License: BSD-3-Clause +Description: sphinxcontrib-log-cabinet + ========================= + + Organize changelogs generated by ``versionadded``, ``versionchanged``, + ``deprecated`` directives. The log will be sorted by newest to oldest + version. For HTML docs, older versions will be collapsed by default. + + Install: + + .. code-block:: text + + $ pip install sphinxcontrib-log-cabinet + + Enable: + + .. code-block:: python + + extensions = [ + ..., + "sphinxcontrib.log_cabinet", + ..., + ] + + Configure: + + ``log_cabinet_collapse_all`` + + By default, current changes and deprecations are not collapsed. Set + this to ``True`` to collapse all changes. + +Platform: UNKNOWN +Classifier: Development Status :: 5 - Production/Stable +Classifier: Intended Audience :: Developers +Classifier: License :: OSI Approved :: BSD License +Classifier: Operating System :: OS Independent +Classifier: Programming Language :: Python +Classifier: Programming Language :: Python :: 2 +Classifier: Programming Language :: Python :: 3 +Classifier: Topic :: Documentation +Classifier: Topic :: Documentation :: Sphinx diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..a67e4d7 --- /dev/null +++ b/README.rst @@ -0,0 +1,29 @@ +sphinxcontrib-log-cabinet +========================= + +Organize changelogs generated by ``versionadded``, ``versionchanged``, +``deprecated`` directives. The log will be sorted by newest to oldest +version. For HTML docs, older versions will be collapsed by default. + +Install: + +.. code-block:: text + + $ pip install sphinxcontrib-log-cabinet + +Enable: + +.. code-block:: python + + extensions = [ + ..., + "sphinxcontrib.log_cabinet", + ..., + ] + +Configure: + +``log_cabinet_collapse_all`` + + By default, current changes and deprecations are not collapsed. Set + this to ``True`` to collapse all changes. diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..3f35035 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,51 @@ +[metadata] +name = sphinxcontrib-log-cabinet +version = 1.0.1 +url = https://github.com/davidism/sphinxcontrib-log-cabinet +license = BSD-3-Clause +license_file = LICENSE.rst +author = David Lord +author_email = davidism@gmail.com +description = Organize changelog directives in Sphinx docs. +long_description = file: README.rst +classifiers = + Development Status :: 5 - Production/Stable + Intended Audience :: Developers + License :: OSI Approved :: BSD License + Operating System :: OS Independent + Programming Language :: Python + Programming Language :: Python :: 2 + Programming Language :: Python :: 3 + Topic :: Documentation + Topic :: Documentation :: Sphinx + +[options] +include_package_data = true +packages = find: +package_dir = + = src +namespace_packages = + sphinxcontrib +install_requires = + Sphinx + +[options.packages.find] +where = src + +[bdist_wheel] +universal = true + +[flake8] +select = B, E, F, W, B9 +ignore = + E203 + E402 + E501 + E722 + W503 +max-line-length = 80 + +[egg_info] +tag_build = +tag_date = 0 + diff --git a/setup.py b/setup.py new file mode 100755 index 0000000..c823345 --- /dev/null +++ b/setup.py @@ -0,0 +1,4 @@ +#!/usr/bin/env python +from setuptools import setup + +setup() diff --git a/src/sphinxcontrib/__init__.py b/src/sphinxcontrib/__init__.py new file mode 100644 index 0000000..5284146 --- /dev/null +++ b/src/sphinxcontrib/__init__.py @@ -0,0 +1 @@ +__import__("pkg_resources").declare_namespace(__name__) diff --git a/src/sphinxcontrib/log_cabinet.py b/src/sphinxcontrib/log_cabinet.py new file mode 100644 index 0000000..ca7463e --- /dev/null +++ b/src/sphinxcontrib/log_cabinet.py @@ -0,0 +1,132 @@ +from itertools import groupby + +from docutils import nodes +from packaging.version import parse as parse_version +from sphinx.addnodes import versionmodified +from sphinx.util import logging + +__version__ = "1.0.1" +logger = logging.getLogger(__name__) + + +def setup(app): + app.add_config_value("log_cabinet_collapse_all", False, "html") + app.connect("doctree-resolved", handle_doctree_resolved) + app.add_node( + CollapsedLog, + html=(html_visit_CollapsedLog, html_depart_CollapsedLog), + latex=(visit_nop, visit_nop), + text=(visit_nop, visit_nop), + man=(visit_nop, visit_nop), + texinfo=(visit_nop, visit_nop), + ) + app.add_config_value("changelog_collapse_all", None, "") + app.connect("config-inited", check_deprecated_config) + return {"version": __version__} + + +def check_deprecated_config(app, config): + if config.changelog_collapse_all is not None: + logger.warning( + "The 'changelog_collapse_all' config has been renamed to" + " 'log_cabinet_collapse_all'. The old name will be removed" + " in version 1.1.0." + ) + + +def _parse_placeholder_version(value, placeholder="x"): + """Strip version suffix (1.1.x to 1.1) before parsing version. + + :param value: Version string to parse. + :param placeholder: Suffix to strip from the version string. + """ + if value.endswith(".{}".format(placeholder)): + value = value[: -(len(placeholder) + 1)] + + return parse_version(value) + + +def handle_doctree_resolved(app, doctree, docname): + visitor = ChangelogVisitor(doctree, app) + doctree.walk(visitor) + collapse_all = app.config.changelog_collapse_all + version = _parse_placeholder_version(app.config.version) + + for after, log in visitor.logs: + if after is None: + # log was the first element of a page + after = log[0] + index = 0 + else: + # log came after other nodes on the page + index = after.parent.index(after) + 1 + + del after.parent[index : index + len(log)] + + if not collapse_all: + visible = [] + hidden = [] + + for n in log: + if parse_version(n["version"]) >= version or n["type"] == "deprecated": + visible.append(n) + else: + hidden.append(n) + + if visible: + after.parent.insert(index, visible) + index += len(visible) + log = hidden + + if log: + collapsed = CollapsedLog() + collapsed.extend(log) + after.parent.insert(index, collapsed) + + +class ChangelogVisitor(nodes.GenericNodeVisitor): + def __init__(self, document, app): + nodes.GenericNodeVisitor.__init__(self, document) + self.logs = [] + + def default_visit(self, node): + after = None + + for key, group in groupby( + node.children, key=lambda n: isinstance(n, versionmodified) + ): + if not key: + after = list(group)[-1] + continue + + self.logs.append( + ( + after, + sorted( + group, key=lambda n: parse_version(n["version"]), reverse=True + ), + ) + ) + + def default_departure(self, node): + pass + + unknown_visit = default_visit + unknown_departure = default_departure + + +class CollapsedLog(nodes.General, nodes.Element): + pass + + +def html_visit_CollapsedLog(self, node): + self.body.append(self.starttag(node, "details", CLASS="changelog")) + self.body.append("Changelog") + + +def html_depart_CollapsedLog(self, node): + self.body.append("") + + +def visit_nop(self, node): + pass diff --git a/src/sphinxcontrib_log_cabinet.egg-info/PKG-INFO b/src/sphinxcontrib_log_cabinet.egg-info/PKG-INFO new file mode 100644 index 0000000..1065154 --- /dev/null +++ b/src/sphinxcontrib_log_cabinet.egg-info/PKG-INFO @@ -0,0 +1,48 @@ +Metadata-Version: 1.1 +Name: sphinxcontrib-log-cabinet +Version: 1.0.1 +Summary: Organize changelog directives in Sphinx docs. +Home-page: https://github.com/davidism/sphinxcontrib-log-cabinet +Author: David Lord +Author-email: davidism@gmail.com +License: BSD-3-Clause +Description: sphinxcontrib-log-cabinet + ========================= + + Organize changelogs generated by ``versionadded``, ``versionchanged``, + ``deprecated`` directives. The log will be sorted by newest to oldest + version. For HTML docs, older versions will be collapsed by default. + + Install: + + .. code-block:: text + + $ pip install sphinxcontrib-log-cabinet + + Enable: + + .. code-block:: python + + extensions = [ + ..., + "sphinxcontrib.log_cabinet", + ..., + ] + + Configure: + + ``log_cabinet_collapse_all`` + + By default, current changes and deprecations are not collapsed. Set + this to ``True`` to collapse all changes. + +Platform: UNKNOWN +Classifier: Development Status :: 5 - Production/Stable +Classifier: Intended Audience :: Developers +Classifier: License :: OSI Approved :: BSD License +Classifier: Operating System :: OS Independent +Classifier: Programming Language :: Python +Classifier: Programming Language :: Python :: 2 +Classifier: Programming Language :: Python :: 3 +Classifier: Topic :: Documentation +Classifier: Topic :: Documentation :: Sphinx diff --git a/src/sphinxcontrib_log_cabinet.egg-info/SOURCES.txt b/src/sphinxcontrib_log_cabinet.egg-info/SOURCES.txt new file mode 100644 index 0000000..8df2405 --- /dev/null +++ b/src/sphinxcontrib_log_cabinet.egg-info/SOURCES.txt @@ -0,0 +1,14 @@ +CHANGES.rst +LICENSE.rst +MANIFEST.in +README.rst +setup.cfg +setup.py +src/sphinxcontrib/__init__.py +src/sphinxcontrib/log_cabinet.py +src/sphinxcontrib_log_cabinet.egg-info/PKG-INFO +src/sphinxcontrib_log_cabinet.egg-info/SOURCES.txt +src/sphinxcontrib_log_cabinet.egg-info/dependency_links.txt +src/sphinxcontrib_log_cabinet.egg-info/namespace_packages.txt +src/sphinxcontrib_log_cabinet.egg-info/requires.txt +src/sphinxcontrib_log_cabinet.egg-info/top_level.txt \ No newline at end of file diff --git a/src/sphinxcontrib_log_cabinet.egg-info/dependency_links.txt b/src/sphinxcontrib_log_cabinet.egg-info/dependency_links.txt new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/src/sphinxcontrib_log_cabinet.egg-info/dependency_links.txt @@ -0,0 +1 @@ + diff --git a/src/sphinxcontrib_log_cabinet.egg-info/namespace_packages.txt b/src/sphinxcontrib_log_cabinet.egg-info/namespace_packages.txt new file mode 100644 index 0000000..aa75604 --- /dev/null +++ b/src/sphinxcontrib_log_cabinet.egg-info/namespace_packages.txt @@ -0,0 +1 @@ +sphinxcontrib diff --git a/src/sphinxcontrib_log_cabinet.egg-info/requires.txt b/src/sphinxcontrib_log_cabinet.egg-info/requires.txt new file mode 100644 index 0000000..2806c16 --- /dev/null +++ b/src/sphinxcontrib_log_cabinet.egg-info/requires.txt @@ -0,0 +1 @@ +Sphinx diff --git a/src/sphinxcontrib_log_cabinet.egg-info/top_level.txt b/src/sphinxcontrib_log_cabinet.egg-info/top_level.txt new file mode 100644 index 0000000..aa75604 --- /dev/null +++ b/src/sphinxcontrib_log_cabinet.egg-info/top_level.txt @@ -0,0 +1 @@ +sphinxcontrib