sphinxnotes-render 1.0b4__tar.gz → 1.0b6__tar.gz

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/sphinx-notes/cookiecutter",
-  "commit": "4c6b17aec1a4b8ddca95c4882c6bed2bc230d595",
+  "commit": "463b120aec3391878cf9453ca26280bf5258c08d",
   "checkout": null,
   "context": {
     "cookiecutter": {
@@ -9,9 +9,11 @@
       "full_name": "sphinxnotes-render",
       "author": "Shengyu Zhang",
       "description": "Define, constrain, and render data in Sphinx documentation",
-      "version": "1.0a0",
+      "version": "1.0b4",
       "github_owner": "sphinx-notes",
       "github_repo": "data",
+      "generated_file_header": "This file is generated from sphinx-notes/cookiecutter.",
+      "dont_edit_header": "DO NOT EDIT.",
       "pypi_name": "sphinxnotes-render",
       "pypi_owner": "SilverRainZ",
       "is_python_project": true,
@@ -20,7 +22,7 @@
       "sphinx_version": "7.0",
       "development_status": "3 - Alpha",
       "_template": "https://github.com/sphinx-notes/cookiecutter",
-      "_commit": "4c6b17aec1a4b8ddca95c4882c6bed2bc230d595"
+      "_commit": "233a8daa4e276a9559975a51178f29e7079dcafd"
     }
   },
   "directory": null

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/.github/workflows/lint.yml

@@ -1,3 +1,5 @@
+# This file is generated from sphinx-notes/cookiecutter.
+
 name: Ruff
 on: [ push, pull_request ]
 
@@ -5,5 +7,5 @@ jobs:
   ruff:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: chartboost/ruff-action@v1

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/.github/workflows/pages.yml

@@ -1,3 +1,5 @@
+# This file is generated from sphinx-notes/cookiecutter.
+
 name: Deploy Sphinx documentation to Pages
 
 # Runs on pushes targeting the default branch

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/.github/workflows/pypi.yml

@@ -1,3 +1,5 @@
+# This file is generated from sphinx-notes/cookiecutter.
+
 name: Publish package distributions to PyPI
 
 on:
@@ -14,8 +16,8 @@ jobs:
     permissions:
       id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
     steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-python@v5
+    - uses: actions/checkout@v6
+    - uses: actions/setup-python@v6
     - run: pip install build twine && make dist
     - uses: pypa/gh-action-pypi-publish@release/v1
       with:

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/.github/workflows/release.yml

@@ -1,3 +1,5 @@
+# This file is generated from sphinx-notes/cookiecutter.
+
 name: Publish Github Release
 
 on:
@@ -11,7 +13,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: ncipollo/release-action@v1
         with:
           body: |

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/.github/workflows/test.yml

@@ -1,3 +1,5 @@
+# This file is generated from sphinx-notes/cookiecutter.
+
 name: Test
 on:
   push:
@@ -8,8 +10,8 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-python@v5
+    - uses: actions/checkout@v6
+    - uses: actions/setup-python@v6
       with:
         python-version-file: 'pyproject.toml'
     - run: python3 -m pip install .[test]
@@ -17,9 +19,10 @@ jobs:
   doctest:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-python@v5
+    - uses: actions/checkout@v6
+    - uses: actions/setup-python@v6
       with:
         python-version-file: 'pyproject.toml'
-    - run: python3 -m pip install .[docs]
+    - run: python3 -m pip install .[test]
+    - run: python3 -m pip install -r docs/requirements.txt
     - run: make doctest

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/.gitignore

@@ -1,3 +1,5 @@
+# This file is generated from sphinx-notes/cookiecutter.
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -135,3 +137,4 @@ poetry.lock
 docs/_build/
 # sphinxnotes-any >= 2.5
 docs/.any*
+.worktrees/

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/.pre-commit-config.yaml

@@ -1,3 +1,5 @@
+# This file is generated from sphinx-notes/cookiecutter.
+
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.14.11

sphinxnotes_render-1.0b6/AGENTS.md

@@ -0,0 +1,40 @@
+<!-- This file is generated from sphinx-notes/cookiecutter. --> 
+
+## 基本说明
+
+这是一个由 SphinxNotes 开发的 Sphinx Extension，由 `sphinxnotes/cookiecutter` 生成，很多基础文件来自模板。
+
+## 首先阅读
+
+- 开始了解项目时，优先阅读 `docs/index.rst`。
+- 如果任务和文档、Sphinx 配置或示例有关，继续阅读 `docs/` 下的其他文件
+
+## 通用知识
+
+- 使用 `make` 会构建 `docs/` 下的文档，文档自依赖当前项目，因此文档构建成功也意味着项目基本能正常构建
+  - `docs/_build` 存放构建好的文档，`make clean` 清除所有构建结果
+  - `make test` 运行测试，测试位于 `tests/`，可能的 e2e 测试位于 `tests/test_e2e.py`
+  - `make doctest` 运行 Sphinx 文档测试
+  - `make install` 使用 `pip install --user` 将项目安装到本地，跨项目测试时常用
+- `make tmpl-*` 用于模板同步，参看 "模板同步" 小节
+
+## 关于 SphinxNotes 项目
+
+- 同为 `sphinxnotes` 项目的其他仓库通常位于当前项目的上一级目录
+- 如果你在阅读代码时遇到本地依赖、模板来源或跨仓库复用关系，可以直接读取这些本地仓库文件，不必先猜测实现，也不必优先去远程搜索。
+- 当我提到 "所有项目" 的时候，请从当前项目的上一级目录的 `cookiecutter/project-list.txt` 获取项目列表
+- `docs/conf.py` 往往会直接从源码树导入当前项目，因此排查文档构建问题时，要同时检查运行时依赖和文档依赖。
+
+## 模板同步
+
+- 先确认任务是当前项目问题，还是模板问题；如果是模板问题，优先在 `sphinxnotes/cookiecutter` 中修复。
+- 模板变更完成后，优先使用 `make tmpl-update` 把改动同步回项目，而不是手工重复修改生成文件。
+- 如果 `make tmpl-update` 产生 `.rej`、冲突或三方合并失败，优先尝试 `make tmpl-apply-rej`，再手工解决冲突。
+- 手工解决冲突时，重点检查 `README.rst`、`pyproject.toml`、`.github/workflows/`、`docs/conf.py`、`docs/requirements.txt` 这些常见受影响文件。
+- 当模板同步结果确认无误后，优先使用 `make tmpl-update-done` 完成后续收尾步骤。
+
+### 修改约定
+
+- 修改模板生成文件时，保留原有注释，除非模板本身已经统一移除了这些注释。
+- 遇到 `CUSTOM ... START` / `END` 这类用户自定义区块时，必须保留这些锚点，并尽量保留区块中的用户内容。
+- 如果模板更新和项目内手工修改发生冲突，优先保护用户自定义内容，再整理模板变更。

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/MANIFEST.in

@@ -1,5 +1,4 @@
 # This file is generated from sphinx-notes/cookiecutter.
-# You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 include LICENSE
 include README.rst

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/Makefile

@@ -1,5 +1,4 @@
 # This file is generated from sphinx-notes/cookiecutter.
-# You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 LANG = en_US.UTF-8
 

{sphinxnotes_render-1.0b4/src/sphinxnotes_render.egg-info → sphinxnotes_render-1.0b6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinxnotes-render
-Version: 1.0b4
+Version: 1.0b6
 Summary: Define, constrain, and render data in Sphinx documentation
 Author: Shengyu Zhang
 Maintainer: Shengyu Zhang
@@ -34,23 +34,11 @@ Requires-Dist: pre-commit; extra == "dev"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: schema; 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"
-Requires-Dist: schema; extra == "docs"
 Provides-Extra: ext
 Requires-Dist: schema; extra == "ext"
 Dynamic: license-file
 
 .. This file is generated from sphinx-notes/cookiecutter.
-   You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 ==================
 sphinxnotes-render

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/README.rst

@@ -1,5 +1,4 @@
 .. This file is generated from sphinx-notes/cookiecutter.
-   You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 ==================
 sphinxnotes-render

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/docs/Makefile

@@ -1,5 +1,4 @@
 # This file is generated from sphinx-notes/cookiecutter.
-# You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 # Minimal makefile for Sphinx documentation
 

sphinxnotes_render-1.0b6/docs/_images/.gitkeep

@@ -0,0 +1 @@
+# This file is generated from sphinx-notes/cookiecutter.

sphinxnotes_render-1.0b6/docs/_static/.gitkeep

@@ -0,0 +1 @@
+# This file is generated from sphinx-notes/cookiecutter.

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/docs/api.rst

@@ -18,22 +18,22 @@ Base Role Classes
 
 .. autoclass:: sphinxnotes.render.BaseContextRole
    :show-inheritance:
-   :members: process_pending_node, queue_pending_node, queue_context, current_context, current_template
+   :members: process_pending_node, queue_pending_node, current_context, current_template
 
 .. autoclass:: sphinxnotes.render.BaseDataDefineRole
    :show-inheritance:
-   :members: process_pending_node, queue_pending_node, queue_context, current_schema, current_template
+   :members: process_pending_node, queue_pending_node, current_schema, current_template
 
 Base Directive Classes
 ----------------------
 
 .. autoclass:: sphinxnotes.render.BaseContextDirective
    :show-inheritance:
-   :members: process_pending_node, queue_pending_node, queue_context, current_raw_data, current_context, current_template
+   :members: process_pending_node, queue_pending_node, current_context, current_template
 
 .. autoclass:: sphinxnotes.render.BaseDataDefineDirective
    :show-inheritance:
-   :members: process_pending_node, queue_pending_node, queue_context, current_raw_data, current_schema, current_template
+   :members: process_pending_node, queue_pending_node, current_raw_data, current_schema, current_template
 
 .. autoclass:: sphinxnotes.render.StrictDataDefineDirective
    :show-inheritance:
@@ -55,22 +55,22 @@ Context refers to the dynamic content of a Jinja template. It can be:
   Our dedicated data type (:py:class:`sphinxnotes.render.ParsedData`), or any
   Python ``dict``.
 
-:py:class:`~sphinxnotes.render.PendingContext`:
+:py:class:`~sphinxnotes.render.UnresolvedContext`:
    Context that is not yet available. For example, it may contain
    :py:class:`unparsed data <sphinxnotes.render.RawData>`,
    remote data, and more.
 
-   :py:class:`PendingContext` can be resolved to
+   :py:class:`UnresolvedContext` can be resolved to
    :py:class:`~sphinxnotes.render.ResolvedContext` by calling
-   :py:meth:`~sphinxnotes.render.PendingContext.resolve`.
+   :py:meth:`~sphinxnotes.render.UnresolvedContext.resolve`.
 
 .. autotype:: sphinxnotes.render.ResolvedContext
 
-.. autoclass:: sphinxnotes.render.PendingContext
+.. autoclass:: sphinxnotes.render.UnresolvedContext
    :members: resolve
 
-``PendingContext`` Implementations
-----------------------------------
+``UnresolvedContext`` Implementations
+-------------------------------------
 
 .. autoclass:: sphinxnotes.render.UnparsedData
    :show-inheritance:
@@ -92,31 +92,33 @@ Extra Context
 =============
 
 See :doc:`tmpl` for built-in extra-context names such as ``doc`` and
-``sphinx``, plus usage examples.
+``env``, plus usage examples.
 
 .. autodecorator:: sphinxnotes.render.extra_context
 
-.. autoclass:: sphinxnotes.render.ParsingPhaseExtraContext
-   :members: phase, generate
+.. autoclass:: sphinxnotes.render.ExtraContext
+   :members: generate
    :undoc-members:
 
-.. autoclass:: sphinxnotes.render.ParsedPhaseExtraContext
-   :members: phase, generate
-   :undoc-members:
-
-.. autoclass:: sphinxnotes.render.ResolvingPhaseExtraContext
-   :members: phase, generate
+.. autoclass:: sphinxnotes.render.ExtraContextRequest
+   :members:
    :undoc-members:
 
-.. autoclass:: sphinxnotes.render.GlobalExtraContext
-   :members: phase, generate
+.. autoclass:: sphinxnotes.render.ExtraContextRegistry
+   :members:
+   :inherited-members:
    :undoc-members:
+   :class-doc-from: both
 
 Filters
 =======
 
 .. autodecorator:: sphinxnotes.render.filter
 
+.. autoclass:: sphinxnotes.render.JinjaRegistry
+   :members:
+   :undoc-members:
+
 Data, Field and Schema
 ======================
 
@@ -139,11 +141,9 @@ Data, Field and Schema
    :members: name, attrs, content
    :undoc-members:
 
-.. autoclass:: sphinxnotes.render.data.Registry
+.. autoclass:: sphinxnotes.render.DataRegistry
    :members:
 
-   .. autotype:: sphinxnotes.render.data.ByOptionStore
-
 Registry
 ========
 
@@ -156,3 +156,7 @@ or add new extra context) by adding new items to
 .. autoclass:: sphinxnotes.render.Registry
 
    .. autoproperty:: data
+
+   .. autoproperty:: extra_context
+
+   .. autoproperty:: jinja

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/docs/changelog.rst

@@ -1,5 +1,4 @@
 .. This file is generated from sphinx-notes/cookiecutter.
-   You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 ==========
 Change Log

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/docs/conf.py

@@ -1,5 +1,4 @@
 # This file is generated from sphinx-notes/cookiecutter.
-# You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 # Configuration file for the Sphinx documentation builder.
 #
@@ -14,7 +13,7 @@ author = 'Shengyu Zhang'
 copyright = "2025, " + author
 
 # The full version, including alpha/beta/rc tags
-version = release = '1.0a0'
+version = release = '1.0b4'
 
 # -- General configuration ---------------------------------------------------
 
@@ -91,6 +90,9 @@ gtagjs_ids = ['G-E4SNX0WZYV']
 extensions.append('sphinx.ext.autodoc')
 autoclass_content = 'init'
 autodoc_typehints = 'description'
+autodoc_default_options = {
+    'member-order': 'bysource',
+}
 
 extensions.append('sphinx.ext.intersphinx')
 intersphinx_mapping = {}
@@ -109,6 +111,7 @@ comboroles_roles = {
     'parsed_literal': (['literal'], True),
 }
 
+
 extensions.append('sphinxnotes.project')
 primary_domain = 'any'
 
@@ -161,6 +164,7 @@ def setup(app):
 
     sys.path.insert(0, test_roots)
     __import__('test-extra-context.conf').conf.setup(app)
+    __import__('test-extra-context-params.conf').conf.setup(app)
     __import__('test-base-context-directive-example.conf').conf.setup(app)
     __import__('test-base-data-define-directive-example.conf').conf.setup(app)
     __import__('test-strict-data-define-directive-example.conf').conf.setup(app)

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/docs/conf.rst

@@ -25,7 +25,5 @@ The extension provides the following configuration:
      - ``text`` (str): the Jinja2 template text.
      - ``on`` (str, optional): same as :rst:dir:`data.template:on`
      - ``debug`` (bool, optional): same as :rst:dir:`data.template:debug`
-     - ``extra`` (list[str], optional): same as :rst:dir:`data.template:extra`
 
    See :ref:`usage-custom-directive` for example.
-

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/docs/ext.rst

@@ -69,11 +69,11 @@ Extending Extra Contexts
 Extra contexts are registered by a
 :py:deco:`sphinxnotes.render.extra_context` class decorator.
 
-The decorated class must be one of the following classes:
-:py:class:`~sphinxnotes.render.ParsingPhaseExtraContext`,
-:py:class:`~sphinxnotes.render.ParsedPhaseExtraContext`,
-:py:class:`~sphinxnotes.render.ResolvingPhaseExtraContext`,
-:py:class:`~sphinxnotes.render.GlobalExtraContext`.
+The decorated class must be a subclass of
+:py:class:`~sphinxnotes.render.ExtraContext`. The ``generate()`` method
+accepts the ``ExtraContextRequest`` as the first argument, plus any
+positional and keyword arguments passed by the template via
+``load_extra()``.
 
 .. literalinclude:: ../tests/roots/test-extra-context/conf.py
    :language: python
@@ -88,10 +88,27 @@ The decorated class must be one of the following classes:
    :style: grid
 
    .. data.render::
-      :extra: cat
 
       {{ load_extra('cat').name }}
 
+To accept custom parameters in your extra context, add ``*args`` and
+``**kwargs`` to the ``generate()`` method signature:
+
+.. literalinclude:: ../tests/roots/test-extra-context-params/conf.py
+   :language: python
+   :start-after: [literalinclude start]
+   :end-before: [literalinclude end]
+
+.. example::
+   :style: grid
+
+   .. data.render::
+
+      {% set docs = load_extra('all_docs', 3) %}
+      {% for doc in docs %}
+      - :doc:`{{ doc }}`
+      {% endfor %}
+
 .. _ext-filters:
 
 Extending ilters

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/docs/index.rst

@@ -1,5 +1,4 @@
 .. This file is generated from sphinx-notes/cookiecutter.
-   You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 ==================
 sphinxnotes-render
@@ -30,14 +29,14 @@ Introduction
 
 This extension mainly consists of two parts:
 
+:parsed_literal:`:ref:\`sphinxnotes.render <framework>\``
+   A framework to define, constrain, and render data in Sphinx documentation.
+
 :parsed_literal:`:ref:\`sphinxnotes.render.ext <extension>\``
    An extension built on top of this framework, allowing user to
    :rst:dir:`define <data.define>`, :rst:dir:`constrain <data.schema>` and
    :rst:dir:`render <data.template>` data entirely through the markup language.
 
-:parsed_literal:`:ref:\`sphinxnotes.render <framework>\``
-   A framework to define, constrain, and render data in Sphinx documentation.
-
 .. INTRODUCTION END
 
 Getting Started

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b6}/docs/make.bat

@@ -1,37 +1,38 @@
-REM This file is generated from sphinx-notes/cookiecutter. DO NOT EDIT.
-
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=python -msphinx
-)
-set SOURCEDIR=.
-set BUILDDIR=_build
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
-	echo.then set the SPHINXBUILD environment variable to point to the full
-	echo.path of the 'sphinx-build' executable. Alternatively you may add the
-	echo.Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-
-:end
-popd
+REM This file is generated from sphinx-notes/cookiecutter.
+REM DO NOT EDIT.
+
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=python -msphinx
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
+	echo.then set the SPHINXBUILD environment variable to point to the full
+	echo.path of the 'sphinx-build' executable. Alternatively you may add the
+	echo.Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

sphinxnotes_render-1.0b6/docs/requirements.txt

@@ -0,0 +1,20 @@
+# This file is generated from sphinx-notes/cookiecutter.
+
+# Documentation build dependencies.
+# Keep these out of pyproject optional-dependencies to avoid resolver issues.
+furo
+sphinx_copybutton
+sphinxcontrib-gtagjs
+sphinx-sitemap
+sphinxext-opengraph
+sphinx-last-updated-by-git
+sphinxnotes-project
+sphinxnotes-comboroles
+
+# NOTE: Not used by docs (docs import extension from ../src),
+# only to resolve its optional dependencies.
+sphinxnotes-render
+
+# CUSTOM DOCS DEPENDENCIES START
+schema # python dict schema validation
+# CUSTOM DOCS DEPENDENCIES END