chore: Update project template to sphinx-notes/cookiecutter@c4f14dab (#8

)

* chore: Update project template to sphinx-notes/cookiecutter@c4f14dab

* chore: Cleanup and format

.cruft.json

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

.github/workflows/lint.yml

@@ -0,0 +1,9 @@
+name: Ruff
+on: [ push, pull_request ]
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: chartboost/ruff-action@v1

.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-isso
+    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-isso
-    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/isso/changelog.html#version-${{ github.ref_name }}
+            Changelog: https://sphinx.silverrainz.me/isso/changelog.html

.gitignore

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

.pre-commit-config.yaml

@@ -0,0 +1,6 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.1
+    hooks:
+      - id: ruff
+      - id: ruff-format

Makefile

@@ -6,21 +6,36 @@ LANG = en_US.UTF-8
 MAKE  = make
 PY    = python3
 RM    = rm -rf
+GIT   = git
+OPEN  = xdg-open
 
 # Build sphinx documentation.
 .PHONY: docs
 docs:
 	$(MAKE) -C docs/
 
+# View sphinx HTML documentation in browser.
+.PHONY: view
+view:
+	$(OPEN) docs/_build/html/index.html
+
+.PHONY: clean
+clean:
+	$(MAKE) -C docs/ clean | true
+	$(RM) dist/ | true
+
+.PHONY: clean
+fmt:
+	ruff format src/
+
 # Run unittest.
 .PHONY: test
 test:
 	$(PY) -m unittest discover -s tests -v
 
 # Build distribution package, for "install" or "upload".
 .PHONY: dist
-dist: pyproject.toml
-	$(RM) dist/ # clean up old dist
+dist: pyproject.toml clean
 	$(PY) -m build
 
 # Install distribution package to user directory.
@@ -51,8 +66,16 @@ 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:
 	@echo -n "Please enter the version to bump: "
 	@read version && $(PY) -m cruft update --variables-to-update "{ \"version\" : \"$$version\" }"
+
+# EXTRA TARGETS START
+
+# EXTRA TARGETS END

README.rst

@@ -5,26 +5,31 @@
 sphinxnotes-isso
 ================
 
-.. image:: https://img.shields.io/github/actions/workflow/status/sphinx-notes/isso/pages.yml
+.. |docs| image:: https://img.shields.io/github/deployments/sphinx-notes/isso/github-pages
    :target: https://sphinx.silverrainz.me/isso
    :alt: Documentation Status
 
-.. image:: https://img.shields.io/github/license/sphinx-notes/isso
-   :target: https://github.com/sphinx-notes/isso/LICENSE
+.. |license| image:: https://img.shields.io/github/license/sphinx-notes/isso
+   :target: https://github.com/sphinx-notes/isso/blob/master/LICENSE
    :alt: Open Source License
 
-.. image:: https://img.shields.io/pypi/v/sphinxnotes-isso.svg
+.. |pypi| image:: https://img.shields.io/pypi/v/sphinxnotes-isso.svg
    :target: https://pypi.python.org/pypi/sphinxnotes-isso
    :alt: PyPI Package
 
-.. image:: https://img.shields.io/pypi/dm/sphinxnotes-isso
+.. |download| image:: https://img.shields.io/pypi/dm/sphinxnotes-isso
    :target: https://pypi.python.org/pypi/sphinxnotes-isso
    :alt: PyPI Package Downloads
 
+|docs| |license| |pypi| |download|
+
 Sphinx extension for embeding Isso comments in documents.
 
-* Documentation: https://sphinx.silverrainz.me/isso
-* Source: https://github.com/sphinx-notes/isso
-* Changelog: https://sphinx.silverrainz.me/isso/changelog.html
-* Tracker: https://github.com/sphinx-notes/isso/issues
-* Download: https://pypi.org/project/sphinxnotes-isso/#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/isso

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,6 +127,24 @@
 extensions.append('sphinxcontrib.gtagjs')
 gtagjs_ids = ['G-E4SNX0WZYV']
 
+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 --------------------------------------------------
 

docs/index.rst

@@ -1,18 +1,38 @@
 .. This file is generated from sphinx-notes/cookiecutter.
    You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
-.. include:: ../README.rst
+================
+sphinxnotes-isso
+================
+
+.. |docs| image:: https://img.shields.io/github/deployments/sphinx-notes/isso/github-pages
+   :target: https://sphinx.silverrainz.me/isso
+   :alt: Documentation Status
+
+.. |license| image:: https://img.shields.io/github/license/sphinx-notes/isso
+   :target: https://github.com/sphinx-notes/isso/blob/master/LICENSE
+   :alt: Open Source License
+
+.. |pypi| image:: https://img.shields.io/pypi/v/sphinxnotes-isso.svg
+   :target: https://pypi.python.org/pypi/sphinxnotes-isso
+   :alt: PyPI Package
+
+.. |download| image:: https://img.shields.io/pypi/dm/sphinxnotes-isso
+   :target: https://pypi.python.org/pypi/sphinxnotes-isso
+   :alt: PyPI Package Downloads
+
+|docs| |license| |pypi| |download|
 
 Introduction
 ============
 
-.. ADDITIONAL CONTENT START
+.. INTRODUCTION START
 
 The extension allows your embedding Isso_ comments in your Sphinx documentation:
 
 .. _Isso: https://isso-comments.de/
 
-.. ADDITIONAL CONTENT END
+.. INTRODUCTION END
 
 Getting Started
 ===============
@@ -28,7 +48,8 @@ First, downloading extension from PyPI:
 
    $ pip install sphinxnotes-isso
 
-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

@@ -38,6 +38,8 @@ dev = [
     "build",
     "twine",
     "cruft",
+    "ruff",
+    "pre-commit"
 ]
 test = [
     "pytest",
@@ -48,6 +50,7 @@ docs = [
     "sphinx_design",
     "sphinx_copybutton",
     "sphinxcontrib-gtagjs",
+    "sphinxnotes-comboroles",
 ]
 
 [project.urls]

ruff.toml

@@ -0,0 +1,9 @@
+# This file is generated from sphinx-notes/cookiecutter.
+# You need to consider modifying the TEMPLATE or modifying THIS FILE.
+
+exclude = [
+    "docs/conf.py",
+]
+
+[format]
+quote-style = "single"