docs: Show examples using any schema (#38)

any schema: https://sphinx.silverrainz.me/any/usage.html#any.Schema
sphinx-notes · Aug 31, 2023 · f0a8bf4 · f0a8bf4
1 parent f6c4d6f
commit f0a8bf4
Show file tree

Hide file tree

Showing 14 changed files with 108 additions and 160 deletions.
diff --git a/docs/_scores/jianpu-directive.txt b/docs/_scores/jianpu-directive.txt
diff --git a/docs/_scores/jianpuinclude-directive.txt b/docs/_scores/jianpuinclude-directive.txt
diff --git a/docs/_scores/lily-directive-c-major-scale.txt b/docs/_scores/lily-directive-c-major-scale.txt
diff --git a/docs/_scores/lily-directive.txt b/docs/_scores/lily-directive.txt
diff --git a/docs/_scores/lily-role.txt b/docs/_scores/lily-role.txt
diff --git a/docs/_scores/lilyinclude-directive.txt b/docs/_scores/lilyinclude-directive.txt
diff --git a/docs/_scores/songbie.jianpu → docs/_scores/songbie.jp b/docs/_scores/songbie.jianpu → docs/_scores/songbie.jp
diff --git a/docs/_templates/example.rst b/docs/_templates/example.rst
@@ -0,0 +1,13 @@
+.. tab-set::
+
+   .. tab-item:: Score
+
+      {% for line in content %}{{ line }}
+      {% endfor %}
+
+   .. tab-item:: Source
+
+      .. code:: rst
+       
+         {% for line in content %}{{ line }}
+         {% endfor %}
diff --git a/docs/_templates/version.rst b/docs/_templates/version.rst
@@ -8,4 +8,3 @@
 {% for line in content %}
 {{ line }}
 {% endfor %}
-
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -21,33 +21,31 @@ Version 2.x
 .. version:: 2.0.0
    :date: 2023-08-18
 
-.. todo https://github.com/sphinx-notes/any/issues/21
+   .. warning:: This release introduces some BREAKING changes.
 
-.. warning:: This release introduces some BREAKING changes.
+   - **BREAKING** changes:
 
-- **BREAKING** changes:
+     - Drop ``:noheader``, ``:nofooter:`` options. User should modifying their Lilypond
+       source to removing header and footer of scores, see `Custom titles headers and footers`__
+       for more details (:issue:`35`)
+     - Drop ``:noedge:`` option and introduce ``:nocrop:`` with opposite meaning compared to before.
+       It is said that score is croppped (noedge) by default
+       By the way, dependencies to Wand and ImageMagick are dropped (:issue:`31`)
+     - Drop ``:audio:`` option and introduce ``:noaudio:`` with opposite meaning compared to before.
+       Audio will be auto-generated when any `MIDI output`__ avaliable, and user set `:noaudio:`
+       only when they don't need this behavior (:pull:`36`)
 
-  - Drop ``:noheader``, ``:nofooter:`` options. User should modifying their Lilypond
-    source to removing header and footer of scores, see `Custom titles headers and footers`__
-    for more details (:issue:`35`)
-  - Drop ``:noedge:`` option and introduce ``:nocrop:`` with opposite meaning compared to before.
-    It is said that score is croppped (noedge) by default
-    By the way, dependencies to Wand and ImageMagick are dropped (:issue:`31`)
-  - Drop ``:audio:`` option and introduce ``:noaudio:`` with opposite meaning compared to before.
-    Audio will be auto-generated when any `MIDI output`__ avaliable, and user set `:noaudio:`
-    only when they don't need this behavior (:pull:`36`)
+   - Enhanced Jianpu support (:issue:`30`)
 
-- Enhanced Jianpu support (:issue:`30`)
+     - Don't panic when Jianpu parsing failed
+     - Can display multiple Jianpu scores, see also `jianpu-ly#35`__
+     - Audio works fine now
 
-  - Don't panic when Jianpu parsing failed
-  - Can display multiple Jianpu scores, see also `jianpu-ly#35`__
-  - Audio works fine now
+   - Score image generataion is reproducible now (:issue:`10`)
 
-- Score image generataion is reproducible now (:issue:`10`)
-
-__ https://lilypond.org/doc/Documentation/notation/creating-titles-headers-and-footers
-__ https://lilypond.org/doc/Documentation/notation/the-midi-block
-__ https://github.com/ssb22/jianpu-ly/issues/35
+   __ https://lilypond.org/doc/Documentation/notation/creating-titles-headers-and-footers
+   __ https://lilypond.org/doc/Documentation/notation/the-midi-block
+   __ https://github.com/ssb22/jianpu-ly/issues/35
 
 Version 1.x
 -----------

diff --git a/docs/conf.py b/docs/conf.py
@@ -111,3 +111,11 @@
 # DOG FOOD CONFIGURATION START
 
 # DOG FOOD CONFIGURATION END
+
+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 }}'))
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -5,88 +5,63 @@ Examples
 The LilyPond documentation used in example can be downloaded here:
 :download:`/_scores/minuet-in-g.ly`.
 
-.. _example-nocrop:
-
 Original paper size
 ===================
 
-.. code-block:: rst
+.. example:: _
 
    .. lilyinclude:: /_scores/minuet-in-g.ly
       :nocrop:
-
-.. lilyinclude:: /_scores/minuet-in-g.ly
-   :nocrop:
 
 .. _example-noaudio:
 
 Disable Audio
 =============
 
-.. code-block:: rst
+.. example:: _
 
    .. lilyinclude:: /_scores/minuet-in-g.ly
       :noaudio:
 
-.. lilyinclude:: /_scores/minuet-in-g.ly
-   :noaudio:
-
-.. _example-transposing:
-
 Transposing
 ===========
 
-.. code-block:: rst
+.. example:: _
 
    .. lilyinclude:: /_scores/minuet-in-g.ly
       :transpose: g c
 
-.. lilyinclude:: /_scores/minuet-in-g.ly
-   :transpose: g c
-
 Multiple Pages
 ==============
 
-.. code-block:: rst
+.. example:: _
 
    .. lilyinclude:: /_scores/alice.ly
 
-.. lilyinclude:: /_scores/alice.ly
-
 Loop
 ====
 
-.. versionadded:: 1.2
-
-.. code-block:: rst
+.. example:: _
 
    .. lilyinclude:: /_scores/minuet-in-g.ly
       :loop:
 
-.. lilyinclude:: /_scores/minuet-in-g.ly
-   :loop:
+.. versionadded:: 1.2
 
 Control Bar at the Top
 ======================
 
-.. versionadded:: 1.3
-
-.. code-block:: rst
+.. example:: _
 
    .. lilyinclude:: /_scores/minuet-in-g.ly
       :controls: top
 
-.. lilyinclude:: /_scores/minuet-in-g.ly
-   :controls: top
+.. versionadded:: 1.3
 
 Jianpu (Numbered Musical Notation)
 ==================================
 
-.. versionadded:: 1.5
-
-.. seealso:: :ref:`jianpu-directive`.
-
-.. code-block:: rst
+.. example:: _
 
    .. jianpu::
 
@@ -97,11 +72,6 @@ Jianpu (Numbered Musical Notation)
 
       1 2 3 4 5 6 7 1'
 
-.. jianpu::
+.. seealso:: :example:`jianpu directive`.
 
-   title=C Major Scale
-   1=C
-   4=60
-   2/4
-
-   1 2 3 4 5 6 7 1'
+.. versionadded:: 1.5
diff --git a/docs/index.rst b/docs/index.rst
@@ -14,7 +14,7 @@ Compared to its predecessor, the extension has many new features such as:
 
 - Play score audio (:doc:`examples`)
 - LaTeX builder support (Since :version:`1.5`)
-- Scale :ref:`example-transposing`
+- Scale :example:`Transposing`
 - :ref:`Jianpu <jianpu-directive>` (Numbered Musical Notation, 简谱) support (Since :version:`1.6.0`)
 - And so on…
 
@@ -70,27 +70,31 @@ Install the follwing runtime dependencies before using the extension:
 We provide :ref:`roles` for embedding score fragment and :ref:`directives` for
 embedding a whole socre:
 
-.. grid:: 2
+.. example::
 
-   .. grid-item-card:: Role
+   :lily:`\relative { c' }` is the first note of the C major scale.
 
-      .. literalinclude:: /_scores/lily-role.txt
-          :language: rst
+.. example::
 
-   .. grid-item-card:: Result
+   .. lily::
 
-       .. include:: /_scores/lily-role.txt
+      \version "2.20.0"
+      \header {
+        title = "C Major Scale"
+      }
 
-.. grid:: 2
+      \score {
+        <<
+          \new Staff {
+              \time 4/4
+              \tempo 4 = 70
+              c' d' e' f' g' a' b' c''
+        }
+        >>
 
-   .. grid-item-card:: Directive
-
-      .. literalinclude:: /_scores/lily-directive-c-major-scale.txt
-          :language: rst
-
-   .. grid-item-card:: Result
-
-       .. include:: /_scores/lily-directive-c-major-scale.txt
+        \midi {}
+        \layout {}
+      }
 
 See :doc:`usage` for more details.