Merge pull request #10 from sphinx-notes/feat/auto-append

feat: Auto append comment thread to documents

Author: SilverRainZ

.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/sphinx-notes/cookiecutter",
-  "commit": "c4f14dab2840eeff6352647a923642b6377d1f49",
+  "commit": "e9395e52b94aa56ef6e2e309df6ef3c2ab877b43",
   "checkout": null,
   "context": {
     "cookiecutter": {
@@ -14,7 +14,8 @@
       "github_repo": "isso",
       "pypi_name": "sphinxnotes-isso",
       "pypi_owner": "SilverRainZ",
-      "_template": "https://github.com/sphinx-notes/cookiecutter"
+      "_template": "https://github.com/sphinx-notes/cookiecutter",
+      "_commit": "e9395e52b94aa56ef6e2e309df6ef3c2ab877b43"
     }
   },
   "directory": null

docs/_templates/confval.rst

@@ -19,6 +19,17 @@ Change Log
 
    Change log here.
 
+Version 2.x
+===========
+
+.. version:: 2.0
+   :date: 2025-02
+
+   - Add :confval:`isso_include_patterns` and :confval:`isso_exclude_patterns`
+     for automaticlly inserting comment thread to the end of document (:pull:`10`)
+   - INCOMPATIBLE CHANGES: Remove the ``:id:`` option of :rst:dir:`isso` directive
+     (:pull:`10`)
+
 Version 1.x
 ===========
 

docs/_templates/example.rst

@@ -74,49 +74,6 @@
 
 # -- Extensions -------------------------------------------------------------
 
-#  
-extensions.append('sphinxnotes.any')
-from sphinxnotes.any import Schema, Field as F
-#
-version_schema = Schema('version',
-                        name=F(unique=True, referenceable=True, required=True, form=F.Form.LINES),
-                        attrs={'date': F(referenceable=True)},
-                        content=F(form=F.Form.LINES),
-                        description_template=open('_templates/version.rst', 'r').read(),
-                        reference_template='🏷️{{ title }}',
-                        missing_reference_template='🏷️{{ title }}',
-                        ambiguous_reference_template='🏷️{{ title }}')
-confval_schema = Schema('confval',
-                        name=F(unique=True, referenceable=True, required=True, form=F.Form.LINES),
-                        attrs={
-                            'type': F(),
-                            'default': F(),
-                            'choice': F(form=F.Form.WORDS),
-                            'versionadded': F(),
-                            'versionchanged': F(form=F.Form.LINES),
-                        },
-                        content=F(),
-                        description_template=open('_templates/confval.rst', 'r').read(),
-                        reference_template='⚙️{{ title }}',
-                        missing_reference_template='⚙️{{ title }}',
-                        ambiguous_reference_template='⚙️{{ title }}')
-example_schema = Schema('example',
-                        name=F(referenceable=True),
-                        attrs={'style': F()},
-                        content=F(form=F.Form.LINES),
-                        description_template=open('_templates/example.rst', 'r').read(),
-                        reference_template='📝{{ title }}',
-                        missing_reference_template='📝{{ title }}',
-                        ambiguous_reference_template='📝{{ title }}')
-#
-any_schemas = [
-    version_schema,
-    confval_schema,
-    example_schema,
-]
-primary_domain = 'any'
-# 
-
 extensions.append('sphinx.ext.extlinks')
 extlinks = {
     'issue': ('https://github.com/sphinx-notes/isso/issues/%s', '💬%s'),
@@ -138,14 +95,14 @@
     'jinja': ('https://jinja.palletsprojects.com/en/latest/', None),
 }
 
-# 
 extensions.append('sphinxnotes.comboroles')
 comboroles_roles = {
     'parsed_literal': (['literal'], True),
 }
-#
 
-#  
+extensions.append('sphinxnotes.project')
+primary_domain = 'any'
+
 # -- Eat your own dog food --------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -159,4 +116,3 @@
 isso_url = 'https://comments.silverrainz.me:30501'
 
 # DOG FOOD CONFIGURATION END
-# 

docs/_templates/version.rst

@@ -6,22 +6,36 @@ Configuration
 
    HTTP URL points to your Isso server.
 
-The following configuration items are corresponding to `Isso Client Configuration`_,
-please use Python's boolean, numeric value instead of string formatted value.
-
-- ``isso_css``
-- ``isso_lang``
-- ``isso_reply_to_self``
-- ``isso_require_author``
-- ``isso_require_email``
-- ``isso_max_comments_top``
-- ``isso_max_comments_nested``
-- ``isso_reveal_on_click``
-- ``isso_avatar``
-- ``isso_avatar_bg``
-- ``isso_avatar_fg``
-- ``isso_vote``
-- ``isso_vote_levels``
-- ``isso_feed``
-
-.. _Isso Client Configuration: https://posativ.org/isso/docs/configuration/client/
+
+.. confval:: isso_client_config
+
+   A mapping that corresponding to `Isso Client Configuration`_.
+
+   .. versionadded:: 2.0
+
+   .. _Isso Client Configuration: https://posativ.org/isso/docs/configuration/client/
+
+
+.. confval:: isso_exclude_patterns
+   type: list[str]
+   default: []
+
+   A list of `glob-style patterns`_ that should be excluded when inserting Isso
+   comment thread.
+   They are matched against the document name (docname).
+   :confval:`isso_exclude_patterns` has priority over :confval:`isso_include_patterns`.
+
+   .. versionadded:: 2.0
+
+   .. _glob-style patterns: https://www.sphinx-doc.org/en/master/usage/configuration.html#glob-style-patterns
+
+
+.. confval:: isso_include_patterns
+   type: list[str]
+   default: []
+
+   A list of `glob-style patterns`_ that are used to insert Isso comment thread.
+   They are matched against the document name (docname).
+   :confval:`isso_exclude_patterns` has priority over :confval:`isso_include_patterns`.
+
+   .. versionadded:: 2.0

docs/changelog.rst

@@ -28,9 +28,15 @@ Introduction
 
 .. INTRODUCTION START
 
-The extension allows your embedding Isso_ comments in your Sphinx documentation:
+The extension allows your embedding Isso_ comments in your Sphinx documentation.
+
+.. note::
+
+   Before using this extension, you should already have an Isso server deployed
+   (`How to deploy a Isso server?`_) and an accessible URL.
 
 .. _Isso: https://isso-comments.de/
+.. _How to deploy a Isso server?: https://isso-comments.de/docs/reference/server-config/
 
 .. INTRODUCTION END
 
@@ -64,18 +70,29 @@ Then, add the extension name to ``extensions`` configuration item in your
 
 .. ADDITIONAL CONTENT START
 
-Set :confval:`isso_url` to the URL of your Isso server.
+Set :confval:`isso_url` to the URL of your Isso server
+(`How to deploy a Isso server?`_):
 
 .. code-block:: python
 
    isso_url = 'https://HOST:PORT'
 
-And then you can use directive ``isso`` to insert a Isso comment box, see
-:doc:`usage` for more details.
+There are two ways to add a comment thread to documentation:
+
+1. Use the :confval:`isso_include_patterns` configuration item. For exampele:
+
+   .. code:: python
+
+      # Enable commenting for all documents
+      isso_include_patterns = ['**']
+
+2. Use the :rst:dir:`isso` directive, this will only affect the current document.
+
+   .. rst-example::
 
-.. example::
+      .. isso::
 
-   .. isso::
+See :doc:`usage` for more details.
 
 Feel free to comment~
 

docs/conf.py

@@ -2,36 +2,68 @@
 Usage
 =====
 
-The ``isso`` directive is used to insert a Isso comment box.
-Each comment thread is distinguished by Isso Thread ID (``data-isso-id``),
-which can be specified via the ``id`` option (see below) or via ``:isso-id``
-docinfo. If no thread ID given, ``/{docname}`` will be used.
+.. note::
 
-The directive supports the following options:
+   Isso only supports rendering **one comment thread on the same page**.
+   If you insert multiple comment threads on the same page, the extra threads
+   will display error messages.
 
-:id: (text)
-    Specify a thread ID, optional
-:title: (text)
-    Specify a thread title rather than use document title
+There are two ways to insert comment thread:
 
-Enable comments for all documents
-=================================
+Manual insert (at a specific location)
+--------------------------------------
 
-Use Sphinx's ``rst_epilog`` confval to append the ``isso`` directive at the
-end of every source file. For example:
+.. rst:directive:: .. isso:: [id]
 
-.. code:: python
+   Insert a Isso comment thread at a specific location.
 
-   rst_epilog = """
-   .. isso::
-   """
+   Threads are distinguished by unique Isso Thread ID (``data-isso-id``),
+   If no thread ID given, ``/{docname}`` (a slash-prefixed document name)
+   will be used.
 
-Disable comments for specified document
----------------------------------------
+   .. rst:directive:option:: title: title
+      :type: text
 
-This extension respects the ``:nocomments`` docinfo__:
+      Indicate thread title rather than use original document title.
 
-   If set, the web application won’t display a comment form for a page generated
-   from this source file.
+Batch insert (at the end of the document)
+-----------------------------------------
 
-__ https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#file-wide-metadata
+If document's docname is matched by :confval:`isso_include_patterns` and
+not matched by :confval:`isso_exclude_patterns`, a comment thread will be
+automaticlly inserted at the end.
+
+For example:
+
+.. code-block:: python
+   :caption: Enable commenting for all documents
+
+   isso_include_patterns = ['**']
+   isso_exclude_patterns = []
+
+.. code-block:: python
+   :caption: Enable commenting for only blog posts
+
+   isso_include_patterns = ['blog/**']
+
+.. code-block:: python
+   :caption: Enable commenting for all documents (except blog posts)
+
+   isso_include_patterns = ['**']
+   isso_exclude_patterns = ['blog/**']
+
+DocInfos
+~~~~~~~~
+
+Users can configure the batched inserted comment thread by setting docinfo_:
+
+:``:isso-id``:
+   Indicate the Isso thread ID, similar to :rst:dir:`isso` directive's argument.
+
+:``:nocomments``:
+   This extension respects the standard ``:nocomments`` docinfo:
+
+      If set, the web application won’t display a comment form for a page generated
+      from this source file.
+
+.. _docinfo: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#file-wide-metadata

docs/conf.rst

@@ -46,7 +46,7 @@ test = [
 ]
 docs = [
     "furo",
-    "sphinxnotes-any",
+    "sphinxnotes-project",
     "sphinx_design",
     "sphinx_copybutton",
     "sphinxcontrib-gtagjs",