Merge pull request #40 from sphinx-notes/template-2023-12-updates

chore: Update cookiecutter template
sphinx-notes · Dec 25, 2023 · 328c282 · 328c282
2 parents b2f059b + 4fb5de6
commit 328c282
Show file tree

Hide file tree

Showing 16 changed files with 169 additions and 76 deletions.
diff --git a/.cruft.json b/.cruft.json
@@ -1,7 +1,7 @@
 {
-  "template": "https://github.com/sphinx-notes/template",
-  "commit": "c781308dbd84e739727ce09aaf798444ced1e7e4",
-  "checkout": null,
+  "template": "https://github.com/sphinx-notes/cookiecutter",
+  "commit": "b0f937e5596c086960ee27cfe0b069947de8a43f",
+  "checkout": "2023-12-updates",
   "context": {
     "cookiecutter": {
       "namespace": "sphinxnotes",
@@ -14,11 +14,7 @@
       "github_repo": "lilypond",
       "pypi_name": "sphinxnotes-lilypond",
       "pypi_owner": "SilverRainZ",
-      "dependencies": [
-        "Sphinx >= 4"
-      ],
-      "additional_docs": [],
-      "_template": "https://github.com/sphinx-notes/template"
+      "_template": "https://github.com/sphinx-notes/cookiecutter"
     }
   },
   "directory": null

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

diff --git a/Makefile b/Makefile
@@ -1,37 +1,58 @@
-# This file is generated from sphinx-notes/template.
+# 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
+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 $</*
 
-.PHONY: test-upload
-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 $</*
 
+# 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,4 @@
-.. This file is generated from sphinx-notes/template.
+.. This file is generated from sphinx-notes/cookiecutter.
    You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 ====================
@@ -17,7 +17,7 @@ sphinxnotes-lilypond
    :target: https://pypi.python.org/pypi/sphinxnotes-lilypond
    :alt: PyPI Package
 
-.. image:: https://img.shields.io/pypi/dw/sphinxnotes-lilypond
+.. image:: https://img.shields.io/pypi/dm/sphinxnotes-lilypond
    :target: https://pypi.python.org/pypi/sphinxnotes-lilypond
    :alt: PyPI Package Downloads
 

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

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
@@ -1,13 +1,32 @@
+
+{% if style is not defined or style == 'tab' %}
 .. tab-set::
 
-   .. tab-item:: Score
+   .. tab-item:: Result
 
       {% for line in content %}{{ line }}
       {% endfor %}
 
-   .. tab-item:: Source
+   .. 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
@@ -1,9 +1,6 @@
-.. list-table::
-   :align: left
-
-   * - :ref:`📅 {{ date }} <any-version.date>`
-     - :tag:`{{ title }}`
 
+:Date: :ref:`📅{{ date }} <any-version.date>`
+:Download: :tag:`{{ title }}`
 
 {% for line in content %}
 {{ line }}

diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -1,4 +1,4 @@
-.. This file is generated from sphinx-notes/template.
+.. This file is generated from sphinx-notes/cookiecutter.
    You need to consider modifying the TEMPLATE or modifying THIS FILE.
 
 ==========
@@ -87,13 +87,13 @@ Version 1.x
 
    - Simplify argument passing between lilypond binding and sphinx extension
    - Add ``loop`` flag for directives
-   - Add confval ``lilypond_audio_volume``
+   - Add confval :confval:`lilypond_audio_volume`
 
 .. version:: 1.1
    :date: 2021-09-12
 
-   - Add confval ``lilypond_png_resolution`` for customizing score resolution in PNG format
-   - Add confval ``lilypond_inline_score_size`` for customizing height of :ref:`inline score <lily-role>`
+   - Add confval :confval:`lilypond_png_resolution` for customizing score resolution in PNG format
+   - Add confval :confval:`lilypond_inline_score_size` for customizing height of :ref:`inline score <lily-role>`
    - Stop using ``<figure>`` as container of block-level score, which is buggy on Safari
 
 .. version:: 1.0

diff --git a/docs/conf.py b/docs/conf.py
@@ -1,4 +1,4 @@
-# This file is generated from sphinx-notes/template.
+# 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.
@@ -70,36 +70,64 @@
 # It is used to indicate the location of document like canonical_url
 html_baseurl = 'https://sphinx.silverrainz.me/lilypond'
 
-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 = [
-    #
-    Schema('version',
-           name=F(unique=True, referenceable=True, required=True),
-           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 }}'),
-    #
+    version_schema,
+    confval_schema,
+    example_schema,
 ]
 primary_domain = 'any'
+#
 
 extensions.append('sphinx.ext.extlinks')
 extlinks = {
-    'issue': ('https://github.com/sphinx-notes/lilypond/issues/%s', '💬 %s'),
-    'pull': ('https://github.com/sphinx-notes/lilypond/pull/%s', '🚀 %s'),
-    'tag': ('https://github.com/sphinx-notes/lilypond/releases/tag/%s', '🏷️ %s'),
+    'issue': ('https://github.com/sphinx-notes/lilypond/issues/%s', '💬%s'),
+    'pull': ('https://github.com/sphinx-notes/lilypond/pull/%s', '🚀%s'),
+    'tag': ('https://github.com/sphinx-notes/lilypond/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,
@@ -110,12 +138,9 @@
 
 # DOG FOOD CONFIGURATION START
 
-# DOG FOOD CONFIGURATION END
+# Use a more relevant example emoji.
+example_schema.reference_template = '🎵 ' + example_schema.reference_template[1:]
+example_schema.missing_reference_template = '🎵 ' + example_schema.missing_reference_template[1:]
+example_schema.ambiguous_reference_template = '🎵 ' + example_schema.ambiguous_reference_template[1:]
 
-any_schemas.append(Schema('example',
-                          name=F(referenceable=True),
-                          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 }}'))
+# DOG FOOD CONFIGURATION END
diff --git a/docs/conf.rst b/docs/conf.rst
@@ -2,41 +2,65 @@
 Configuration
 =============
 
-.. hint:: Normally, extensions should work without any configuration
+.. hint:: In most cases, the extension should work without any configuration.
+
+.. confval:: lilypond_lilypond_args:
+   :type: list[str]
+   :default: ['lilypond']
+   :versionadded: 1.4
 
-:lilypond_lilypond_args: (Type: ``list[str]``, Default: ``['lilypond']``)
    Argument list for running `LilyPond`_. The first one is path to LilyPond binary.
-:lilypond_timidity_args: (Type: ``list[str]``, Default: ``['timidity']``)
+
+.. confval:: lilypond_timidity_args
+   :type: list[str]
+   :default: ['timidity']
+
    Argument list for running `Timidity++`_. The first one is path to Timidity++ binary.
-:lilypond_ffmpeg_args: (Type: ``list[str]``, Default: ``['ffmpeg']``)
-   Argument list for running FFmpeg_. The first one is path to FFmpeg binary.
 
-   .. versionadded:: 1.4
+.. confval:: lilypond_ffmpeg_args
+   :type: list[str]
+   :default: ['ffmpeg']
+
+   Argument list for running FFmpeg_. The first one is path to FFmpeg binary.
 
-:lilypond_score_format: (Type: ``str``, Default: ``'png'``)
-   Format of outputed scores, available values: ``['png', 'svg', 'pdf', 'eps']``.
-:lilypond_audio_format: (Type: ``str``, Default: ``'wav'``)
-   Format of outputed audio, available values: ``['wav', 'ogg', 'mp3']``.
+.. confval:: lilypond_score_format
+   :Type: str
+   :default: 'png'
+   :choice: 'png' 'svg' 'pdf' 'eps'
 
-   .. versionchanged:: 1.4
+   Format of outputed scores
 
+.. confval:: lilypond_audio_format
+   :type: str
+   :default: 'wav'
+   :choice: 'wav' 'ogg' 'mp3'
+   :versionchanged:
+      1.4
       Add support for 'mp3' audio format
 
-:lilypond_audio_volume: (Type: ``int``, Default: `None`)
+   Format of outputed audio, available values: 
+
+.. confval:: lilypond_audio_volume
+   :type: int
+   :default: none
+   :versionadded: 1.2
+
    Volume of outputed audio, will be converted to value of `Timidity++`_ argument ``--volume``.
 
-   .. versionadded:: 1.2
+.. confval:: lilypond_png_resolution
+   :type: int
+   :default: 300
+   :versionadded: 1.1
 
-:lilypond_png_resolution: (Type: ``int``, Default: ``300``)
    Resolution in DPI of score in PNG format, will be converted to value of LilyPond_ argument ``-dresolution``.
 
-   .. versionadded:: 1.1
 
-:lilypond_inline_score_size: (Type: ``str``, Default: ``2.5em``)
-   Line height of :ref:`inline socre <lily-role>`, will be converted to value of `CSS height`_.
-
-   .. versionadded:: 1.1
+.. confval:: lilypond_inline_score_size
+   :type: str
+   :default: '2.5em'
+   :versionadded: 1.1
 
+   Line height of :ref:`inline socre <lily-role>`, will be converted to value of `CSS height`_.
 
 .. _LilyPond: https://lilypond.org/
 .. _FFmpeg: https://ffmpeg.org/