refactor: Sync with template and use cruft (#4)

sphinx-notes · May 1, 2024 · 8ede5b9 · 8ede5b9
1 parent bc7791b
commit 8ede5b9
Show file tree

Hide file tree

Showing 23 changed files with 346 additions and 160 deletions.
diff --git a/.cruft.json b/.cruft.json
@@ -0,0 +1,21 @@
+{
+  "template": "https://github.com/sphinx-notes/cookiecutter",
+  "commit": "1701bf78ca498d756ce4502aa1712cfe23ed35af",
+  "checkout": null,
+  "context": {
+    "cookiecutter": {
+      "namespace": "sphinxnotes",
+      "name": "isso",
+      "full_name": "sphinxnotes-isso",
+      "author": "Shengyu Zhang",
+      "description": "Sphinx extension for embeding Isso comments in documents",
+      "version": "1.0",
+      "github_owner": "sphinx-notes",
+      "github_repo": "isso",
+      "pypi_name": "sphinxnotes-isso",
+      "pypi_owner": "SilverRainZ",
+      "_template": "https://github.com/sphinx-notes/cookiecutter"
+    }
+  },
+  "directory": null
+}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,36 @@
+name: Publish New Release
+
+on:
+  push:
+    tags:
+      - "*"
+
+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
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ncipollo/release-action@v1
+        with:
+          body: |
+            Changelog: https://sphinx.silverrainz.me/isso/changelog.html#version-${{ github.ref_name }}
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2023, Shengyu Zhang
+Copyright (c) 2024, Shengyu Zhang
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,4 +1,5 @@
-# This file is generated from sphinx-notes/template. DO NOT EDIT.
+# This file is generated from sphinx-notes/cookiecutter.
+# You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 include LICENSE
 include README.rst

diff --git a/Makefile b/Makefile
@@ -1,31 +1,58 @@
-# This file is generated from sphinx-notes/template. DO NOT EDIT.
+# This file is generated from sphinx-notes/cookiecutter.
+# You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 LANG = en_US.UTF-8
 
-MAKE = make
-PY   = python3
-RM   = rm -rf
-
-.PHONY: docs test dist install upload test-upload sync-template
+MAKE  = make
+PY    = python3
+RM    = rm -rf
 
+# Build sphinx documentation.
+.PHONY: docs
 docs:
 	$(MAKE) -C docs/
 
+# 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
 	$(PY) -m build
 
+# Install distribution package to user directory.
+#
+# NOTE: It may breaks your system-level packages, use at your own risk.
+.PHONY: install
 install: dist
+	export PIP_BREAK_SYSTEM_PACKAGES=1 # required by Python 3.11+, see PEP-668
 	$(PY) -m pip install --user --no-deps --force-reinstall dist/*.whl
 
+# Publish wheel to PyPI offical server <https://pypi.org/> when you want to
+# You should have a PyPI account and have PyPI token configured.
+#
+# See also https://packaging.python.org/en/latest/tutorials/packaging-projects/#uploading-the-distribution-archives
+.PHONY: upload
 upload: dist
 	$(PY) -m twine upload --repository pypi $</*
 
-test-upload: dist
+# Same to the aboved "upload" target, but this publishs to PyPI test server
+# <https://test.pypi.org/>.
+.PHONY: upload-test
+upload-test: dist
 	$(PY) -m twine upload --repository testpypi $</*
 
-sync-template:
-	./.sphinxnotes/template/update.py
+# Keep up to date with the latest template.
+# See also https://github.com/sphinx-notes/cookiecutter.
+.PHONY: update-template
+update-template:
+	$(PY) -m cruft update
+
+# 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\" }"
diff --git a/README.rst b/README.rst
@@ -1,4 +1,5 @@
-.. This file is generated from sphinx-notes/template. DO NOT EDIT.
+.. This file is generated from sphinx-notes/cookiecutter.
+   You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 ================
 sphinxnotes-isso
@@ -16,7 +17,7 @@ sphinxnotes-isso
    :target: https://pypi.python.org/pypi/sphinxnotes-isso
    :alt: PyPI Package
 
-.. image:: https://img.shields.io/pypi/dw/sphinxnotes-isso
+.. image:: https://img.shields.io/pypi/dm/sphinxnotes-isso
    :target: https://pypi.python.org/pypi/sphinxnotes-isso
    :alt: PyPI Package Downloads
 

diff --git a/docs/Makefile b/docs/Makefile
@@ -1,5 +1,6 @@
-# This file is generated from sphinx-notes/template. DO NOT EDIT.
-#
+# This file is generated from sphinx-notes/cookiecutter.
+# You need to consider modifying the TEMPLATE or modifying THIS FILE.
+
 # Minimal makefile for Sphinx documentation
 
 # You can set these variables from the command line.

diff --git a/docs/_images/.gitkeep b/docs/_images/.gitkeep
diff --git a/docs/_images/sphinx-notes.png → docs/_static/sphinx-notes.png b/docs/_images/sphinx-notes.png → docs/_static/sphinx-notes.png
diff --git a/docs/_templates/confval.rst b/docs/_templates/confval.rst
@@ -0,0 +1,11 @@
+
+:Type: :py:class:`{{ type }}`
+:Default: ``{{ default }}``
+{% if choice %}:Choices: {% for c in choice %}``{{ c }}`` {% endfor %}{% endif %}
+{% if versionadded %}:Version added: :version:`{{ versionadded }}`{% endif %}
+{% if versionchanged %}:Version changed:{% for i in range(0, versionchanged|count -1, 2)  %}
+   :version:`{{ versionchanged[i] }}`
+      {{ versionchanged[i+1] }}{% endfor %}{% endif %}
+
+{{ content }}
+
diff --git a/docs/_templates/example.rst b/docs/_templates/example.rst
@@ -0,0 +1,31 @@
+
+{% if style is not defined or style == 'tab' %}
+.. tab-set::
+
+   .. tab-item:: Result
+
+      {% for line in content %}{{ line }}
+      {% endfor %}
+
+   .. tab-item:: reStructuredText
+
+      .. code:: rst
+
+         {% for line in content %}{{ line }}
+         {% endfor %}
+{% elif style == 'grid'  %}
+.. grid:: 2
+
+   .. grid-item-card::  reStructuredText
+
+      .. code:: rst
+
+         {% for line in content %}{{ line }}
+         {% endfor %}
+
+   .. grid-item-card:: Result
+
+      {% for line in content %}{{ line }}
+      {% endfor %}
+{% endif %}
+
diff --git a/docs/_templates/version.rst b/docs/_templates/version.rst
@@ -0,0 +1,8 @@
+
+:Date: :ref:`📅{{ date }} <any-version.date>`
+:Download: :tag:`{{ title }}`
+
+{% for line in content %}
+{{ line }}
+{% endfor %}
+
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -1,24 +1,34 @@
+.. This file is generated from sphinx-notes/cookiecutter.
+   You need to consider modifying the TEMPLATE or modifying THIS FILE.
+
 ==========
 Change Log
 ==========
 
-2021-04-21 1.0
---------------
+.. Example:
+
+   1.0.0
+   =====
+
+   .. version:: _
+      :date: yyyy-mm-dd
 
-.. sectionauthor:: Shengyu Zhang
+      Change log here.
 
-- Use document title as Isso thread title
+Version 1.x
+===========
 
-2021-03-23 1.0a2
-----------------
+.. version:: 1.0
+   :date: 2021-04-21
 
-.. sectionauthor:: Shengyu Zhang
+   - Use document title as Isso thread title
 
-- Fixes: Thread ID should starts with slash
+.. version:: 1.0a2
+   :date: 2021-03-23
 
-2021-03-13 1.0a1
-----------------
+   - Fixes: Thread ID should starts with slash
 
-.. sectionauthor:: Shengyu Zhang
+.. version:: 1.0a1
+   :date: 2021-03-13
 
-The first version is out, enjoy~
+   The first version is out, enjoy~
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,5 +1,6 @@
-# This file is generated from sphinx-notes/template. DO NOT EDIT.
-#
+# 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.
 #
 # This file only contains a selection of the most common options. For a full
@@ -13,28 +14,22 @@
 
 project = 'sphinxnotes-isso'
 author = 'Shengyu Zhang'
-copyright = "2023, " + author
+copyright = "2024, " + author
 
 # The full version, including alpha/beta/rc tags
-version = release = '1.0-5-ga40c37d'
+version = release = '1.0'
 
 # -- General configuration ---------------------------------------------------
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('../src/sphinxnotes'))
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
     'sphinx.ext.githubpages',
-    'isso',
+    'sphinx_design',
+    'sphinx_copybutton',
 ]
 
-isso_url = 'https://comments.silverrainz.me:30501'
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -75,4 +70,75 @@
 # It is used to indicate the location of document like canonical_url
 html_baseurl = 'https://sphinx.silverrainz.me/isso'
 
-html_logo = html_favicon = '_images/sphinx-notes.png'
+html_logo = html_favicon = '_static/sphinx-notes.png'
+
+# -- 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'),
+    'pull': ('https://github.com/sphinx-notes/isso/pull/%s', '🚀%s'),
+    'tag': ('https://github.com/sphinx-notes/isso/releases/tag/%s', '🏷️%s'),
+}
+
+extensions.append('sphinxcontrib.gtagjs')
+gtagjs_ids = ['G-E4SNX0WZYV']
+
+#  
+# -- Eat your own dog food --------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../src/sphinxnotes'))
+extensions.append('isso')
+
+# DOG FOOD CONFIGURATION START
+
+isso_url = 'https://comments.silverrainz.me:30501'
+
+# DOG FOOD CONFIGURATION END
+#