chore: Update project template to sphinx-notes/cookiecutter@0db2ed86

.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/sphinx-notes/template",
-  "commit": "1701bf78ca498d756ce4502aa1712cfe23ed35af",
+  "commit": "0db2ed864acc101a2ee90a3bf94b54b9f46473cf",
   "checkout": null,
   "context": {
     "cookiecutter": {

.github/workflows/pypi.yml

@@ -0,0 +1,22 @@
+name: Publish package distributions to PyPI
+
+on:
+  push:
+    tags:
+      - "*"
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sphinxnotes-snippet
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+    - run: pip install build twine && make dist
+    - uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/release.yml

@@ -1,30 +1,12 @@
-name: Publish New Release
+name: Publish Github Release
 
 on:
   push:
     tags:
-      - "*"
+      - "[0-9]+.[0-9]+" # MAJOR.MINOR (1.0: y, 1.0a0: n, 1.0.1: n)
 
 jobs:
-  pypi:
-    name: Publish package distributions to PyPI
-    runs-on: ubuntu-latest
-    environment:
-      name: pypi
-      url: https://pypi.org/p/sphinxnotes-snippet
-    permissions:
-      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
-    steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-python@v5
-    - run: pip install build twine && make dist
-    - uses: pypa/gh-action-pypi-publish@release/v1
-      with: 
-        password: ${{ secrets.PYPI_API_TOKEN }}
-
   release:
-    name: Publish Github Release
-    needs: [pypi]
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -33,4 +15,4 @@ jobs:
       - uses: ncipollo/release-action@v1
         with:
           body: |
-            Changelog: https://sphinx.silverrainz.me/snippet/changelog.html#version-${{ github.ref_name }}
+            Changelog: https://sphinx.silverrainz.me/snippet/changelog.html

.gitignore

@@ -133,3 +133,5 @@ poetry.lock
 
 # Sphinx
 docs/_build/
+# sphinxnotes-any >= 2.5
+docs/.any*

Makefile

@@ -6,6 +6,7 @@ LANG = en_US.UTF-8
 MAKE  = make
 PY    = python3
 RM    = rm -rf
+GIT   = git
 
 # Build sphinx documentation.
 .PHONY: docs
@@ -51,6 +52,10 @@ upload-test: dist
 update-template:
 	$(PY) -m cruft update
 
+.PHONY: update-template-done
+update-template-done:
+	$(GIT) commit -m "chore: Update project template to sphinx-notes/cookiecutter@$(shell jq -r '.commit' .cruft.json | head -c8)"
+
 # Update project version.
 .PHONY: bump-version
 bump-version:

README.rst

@@ -5,26 +5,31 @@
 sphinxnotes-snippet
 ===================
 
-.. image:: https://img.shields.io/github/actions/workflow/status/sphinx-notes/snippet/pages.yml
+.. |docs| image:: https://img.shields.io/github/deployments/sphinx-notes/snippet/github-pages
    :target: https://sphinx.silverrainz.me/snippet
    :alt: Documentation Status
 
-.. image:: https://img.shields.io/github/license/sphinx-notes/snippet
-   :target: https://github.com/sphinx-notes/snippet/LICENSE
+.. |license| image:: https://img.shields.io/github/license/sphinx-notes/snippet
+   :target: https://github.com/sphinx-notes/snippet/blob/master/LICENSE
    :alt: Open Source License
 
-.. image:: https://img.shields.io/pypi/v/sphinxnotes-snippet.svg
+.. |pypi| image:: https://img.shields.io/pypi/v/sphinxnotes-snippet.svg
    :target: https://pypi.python.org/pypi/sphinxnotes-snippet
    :alt: PyPI Package
 
-.. image:: https://img.shields.io/pypi/dm/sphinxnotes-snippet
+.. |download| image:: https://img.shields.io/pypi/dm/sphinxnotes-snippet
    :target: https://pypi.python.org/pypi/sphinxnotes-snippet
    :alt: PyPI Package Downloads
 
+|docs| |license| |pypi| |download|
+
 Sphinx documentation snippets manager.
 
-* Documentation: https://sphinx.silverrainz.me/snippet
-* Source: https://github.com/sphinx-notes/snippet
-* Changelog: https://sphinx.silverrainz.me/snippet/changelog.html
-* Tracker: https://github.com/sphinx-notes/snippet/issues
-* Download: https://pypi.org/project/sphinxnotes-snippet/#files
+.. INTRODUCTION START 
+   (MUST written in standard reStructuredText, without Sphinx stuff)
+
+.. INTRODUCTION END
+
+Please refer to Documentation_ for more details.
+
+.. _Documentation: https://sphinx.silverrainz.me/snippet

docs/changelog.rst

@@ -5,15 +5,19 @@
 Change Log
 ==========
 
+.. hint:: You may want to learn about our `Release Strategy`__
+
+   __ https://sphinx.silverrainz.me/release.html
+
 .. Example:
 
-   1.0.0
-   =====
+   1.0
+   ===
 
    .. version:: _
       :date: yyyy-mm-dd
 
-      Change log here.
+   Change log here.
 
 Version 1.x
 ===========

docs/conf.py

@@ -127,7 +127,23 @@
 extensions.append('sphinxcontrib.gtagjs')
 gtagjs_ids = ['G-E4SNX0WZYV']
 
-extensions.append('sphinxcontrib.asciinema')
+extensions.append('sphinx.ext.autodoc')
+autoclass_content = 'init'
+autodoc_typehints = 'description'
+
+extensions.append('sphinx.ext.intersphinx')
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master', None),
+    'jinja': ('https://jinja.palletsprojects.com/en/latest/', None),
+}
+
+# 
+extensions.append('sphinxnotes.comboroles')
+comboroles_roles = {
+    'parsed_literal': (['literal'], True),
+}
+#
 
 #
 # -- Eat your own dog food --------------------------------------------------
@@ -144,5 +160,7 @@
     'cache_dir': '/tmp/' + 'sphinxnotes-snippet'
 }
 
+extensions.append('sphinxcontrib.asciinema')
+
 # DOG FOOD CONFIGURATION END
 #

docs/index.rst

@@ -1,20 +1,40 @@
 .. This file is generated from sphinx-notes/cookiecutter.
    You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
-.. include:: ../README.rst
+===================
+sphinxnotes-snippet
+===================
+
+.. |docs| image:: https://img.shields.io/github/deployments/sphinx-notes/snippet/github-pages
+   :target: https://sphinx.silverrainz.me/snippet
+   :alt: Documentation Status
+
+.. |license| image:: https://img.shields.io/github/license/sphinx-notes/snippet
+   :target: https://github.com/sphinx-notes/snippet/blob/master/LICENSE
+   :alt: Open Source License
+
+.. |pypi| image:: https://img.shields.io/pypi/v/sphinxnotes-snippet.svg
+   :target: https://pypi.python.org/pypi/sphinxnotes-snippet
+   :alt: PyPI Package
+
+.. |download| image:: https://img.shields.io/pypi/dm/sphinxnotes-snippet
+   :target: https://pypi.python.org/pypi/sphinxnotes-snippet
+   :alt: PyPI Package Downloads
+
+|docs| |license| |pypi| |download|
 
 Introduction
 ============
 
-.. ADDITIONAL CONTENT START
+.. INTRODUCTION START
 
 Documentations in Sphinx can be parsed into doctree_ (In other words, Abstract Syntax Tree), all contents of documents are parsed into node of this tree. The :ref:`ext` collects snippets (doctree nodes) during the build phase of Sphinx, and provide a :ref:`cli` for your accessing.
 
 For more details, please refer to :doc:`intro`
 
 .. _doctree: https://docutils.sourceforge.io/docs/ref/doctree.html
 
-.. ADDITIONAL CONTENT END
+.. INTRODUCTION END
 
 Getting Started
 ===============
@@ -30,7 +50,8 @@ First, downloading extension from PyPI:
 
    $ pip install sphinxnotes-snippet
 
-Then, add the extension name to ``extensions`` configuration item in your conf.py_:
+Then, add the extension name to ``extensions`` configuration item in your
+:parsed_literal:`conf.py_`:
 
 .. code-block:: python
 

pyproject.toml

@@ -57,6 +57,7 @@ docs = [
     "sphinx_design",
     "sphinx_copybutton",
     "sphinxcontrib-gtagjs",
+    "sphinxnotes-comboroles",
     "sphinxcontrib.asciinema",
 ]