diff --git a/.cruft.json b/.cruft.json new file mode 100644 index 0000000..9c96175 --- /dev/null +++ b/.cruft.json @@ -0,0 +1,25 @@ +{ + "template": "https://github.com/sphinx-notes/template", + "commit": "202f9756fdd661ab195d20bb6926a9481ee1d78a", + "checkout": null, + "context": { + "cookiecutter": { + "namespace": "sphinxnotes", + "name": "lilypond", + "full_name": "sphinxnotes-lilypond", + "author": "Shengyu Zhang", + "description": "Sphinx extension for embedding LilyPond scores", + "version": "1.6.0", + "github_owner": "sphinx-notes", + "github_repo": "lilypond", + "pypi_name": "sphinxnotes-lilypond", + "pypi_owner": "SilverRainZ", + "dependencies": [ + "Sphinx >= 4" + ], + "additional_docs": [], + "_template": "https://github.com/sphinx-notes/template" + } + }, + "directory": null +} diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 79c7c08..42ff84b 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -1,29 +1,36 @@ -name: Pages +name: Deploy Sphinx documentation to Pages + +# Runs on pushes targeting the default branch on: push: - branches: - - master + branches: [master] + +# Cancel any in-progress job or run +# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency +concurrency: + group: ${{ github.ref }} + cancel-in-progress: true + jobs: - build: + pages: runs-on: ubuntu-20.04 + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + permissions: + pages: write + id-token: write steps: - - name: Setup locale - run: | + - run: | sudo locale-gen en_US.UTF-8 sudo update-locale - - name: Install dependencies - run: | sudo apt-get update; sudo apt-get install lilypond timidity imagemagick fonts-noto-cjk - - name: Checkout - uses: actions/checkout@master + - uses: actions/checkout@master with: - fetch-depth: 0 # otherwise, you will failed to push refs to dest repo + fetch-depth: 0 submodules: true # for jianpu-ly - - name: Build and Commit - uses: sphinx-notes/pages@v2 - - name: Push changes - uses: ad-m/github-push-action@master + - id: deployment + uses: sphinx-notes/pages@v3 with: - github_token: ${{ secrets.GITHUB_TOKEN }} - branch: gh-pages + checkout: false diff --git a/.gitignore b/.gitignore index 5f19aeb..6f2c745 100644 --- a/.gitignore +++ b/.gitignore @@ -128,5 +128,8 @@ dmypy.json # Pyre type checker .pyre/ -# Sphinx build dir -_build/ +# Poetry +poetry.lock + +# Sphinx +docs/_build/ diff --git a/LICENSE b/LICENSE index a57aa87..e15ff86 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2020, Sphinx Notes +Copyright (c) 2023, Shengyu Zhang All rights reserved. Redistribution and use in source and binary forms, with or without @@ -26,4 +26,4 @@ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. \ No newline at end of file diff --git a/MANIFEST.in b/MANIFEST.in index 8c37b94..6b5bf17 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,11 @@ -include README.rst +# This file is generated from sphinx-notes/template. +# You need to consider modifying the TEMPLATE or modifying THIS FILE. + include LICENSE -recursive-include doc * -prune doc/_build +include README.rst + +recursive-include tests * +recursive-exclude * __pycache__ +recursive-exclude * *.py[co] + +recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif diff --git a/Makefile b/Makefile index ab42553..59bad58 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,7 @@ -LANG=en_US.UTF-8 +# This file is generated from sphinx-notes/template. +# You need to consider modifying the TEMPLATE or modifying THIS FILE. + +LANG = en_US.UTF-8 MAKE = make PY = python3 @@ -8,20 +11,27 @@ RM = rm -rf docs: $(MAKE) -C docs/ -.PHONY: dist -dist: setup.py - $(RM) dist/ build/ *.egg-info/ - $(PY) setup.py sdist bdist_wheel - $(PY) -m twine check dist/* +.PHONY: test +test: + $(PY) -m unittest discover -s tests -v -.PHONY: upload -upload: dist/ - $(PY) -m twine upload --repository pypi $<* +.PHONY: dist +dist: pyproject.toml + $(RM) dist/ # clean up old dist + $(PY) -m build .PHONY: install install: dist $(PY) -m pip install --user --no-deps --force-reinstall dist/*.whl -.PHONY: test -test: tests - $(PY) -m unittest discover -s tests -v +.PHONY: upload +upload: dist + $(PY) -m twine upload --repository pypi $> + } diff --git a/docs/lily-directive-example.txt b/docs/_scores/lily-directive.txt similarity index 100% rename from docs/lily-directive-example.txt rename to docs/_scores/lily-directive.txt diff --git a/docs/lily-role-example.txt b/docs/_scores/lily-role.txt similarity index 100% rename from docs/lily-role-example.txt rename to docs/_scores/lily-role.txt diff --git a/docs/_scores/lilyinclude-directive.txt b/docs/_scores/lilyinclude-directive.txt new file mode 100644 index 0000000..6a24404 --- /dev/null +++ b/docs/_scores/lilyinclude-directive.txt @@ -0,0 +1,4 @@ +.. lilyinclude:: /_scores/witch-spring.ly + :nofooter: + :noedge: + :audio: diff --git a/docs/minuet-in-g.ly b/docs/_scores/minuet-in-g.ly similarity index 100% rename from docs/minuet-in-g.ly rename to docs/_scores/minuet-in-g.ly diff --git a/docs/witch-spring.ly b/docs/_scores/witch-spring.ly similarity index 100% rename from docs/witch-spring.ly rename to docs/_scores/witch-spring.ly diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/_templates/version.rst b/docs/_templates/version.rst new file mode 100644 index 0000000..f9f8623 --- /dev/null +++ b/docs/_templates/version.rst @@ -0,0 +1,11 @@ +.. list-table:: + :align: left + + * - :ref:`📅 {{ date }} ` + - :tag:`{{ title }}` + + +{% for line in content %} +{{ line }} +{% endfor %} + diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 0000000..afb273b --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,89 @@ +.. This file is generated from sphinx-notes/template. + You need to consider modifying the TEMPLATE or modifying THIS FILE. + +========== +Change Log +========== + +.. Example: + + 1.0.0 + ===== + + .. version:: _ + :date: yyyy-mm-dd + + Change log here. + +Version 1.x +----------- + +.. version:: 1.6.0 + :date: 2022-10-08 + + - Fix resolution of SVG output (:pull:`18`) + - Add basic Jianpu (Numbered Musical Notation) support (:issue:`17`) + - Don't panic when running unsupported builders (:issue:`20`) + +.. version:: 1.5 + :date: 2022-03-13 + + - Add LaTeX builder suppport (:issue:`11`) + +.. version:: 1.4 + :date: 2021-12-19 + + - Note ly files as dependencies, so Sphinx will rebuild document when ly file changes + - Won't crash when score file does not exist + - Left a "system message" paragraphs when score build failed + - Add support for MP3 audio format, FFmpeg_ is required + + .. _FFmpeg: https://ffmpeg.org/ + +Version 1.3 +----------- + +.. version:: 1.3 + :date: 2021-11-07 + + - Add ``controls`` flag for specifing the position of the control bar + +.. version:: 1.2 + :date: 2021-09-17 + + - Simplify argument passing between lilypond binding and sphinx extension + - Add ``loop`` flag for directives + - Add 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 ` + - Stop using ``
`` as container of block-level score, which is buggy on Safari + +.. version:: 1.0 + :date: 2021-06-26 + + - Rebuild env when configuration changed + - Fix wrong license value + +Pre-release +----------- + +.. version:: 1.0a2 + :date: 2020-12-27 + + - Support multiple pages documents + - Imporve of lilypond outputs cache + +.. version:: 1.0a1 + :date: 2020-12-26 + + - Fix invalid insertion of ``\header`` + - Set default audio format to wav + +.. version:: 1.0a0 + :date: 2020-12-06 + + The alpha version is out, enjoy~ diff --git a/docs/conf.py b/docs/conf.py index 65b3477..5a8de28 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,32 +1,23 @@ +# This file is generated from sphinx-notes/template. +# 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 # list see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html -# -- Path setup -------------------------------------------------------------- - -# 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. -# import os import sys -from datetime import datetime -# Import proj's meta info -sys.path.insert(0, os.path.abspath('../sphinxnotes')) -# Import proj's meta info -import lilypond as proj # -- Project information ----------------------------------------------------- -project = proj.__title__ -copyright = '%s, %s' % (datetime.now().year, proj.__author__) -author = proj.__author__ +project = 'sphinxnotes-lilypond' +author = 'Shengyu Zhang' +copyright = "2023, " + author # The full version, including alpha/beta/rc tags -version = release = proj.__version__ - +version = release = '1.6.0' # -- General configuration --------------------------------------------------- @@ -35,7 +26,8 @@ # ones. extensions = [ 'sphinx.ext.githubpages', - 'lilypond', + 'sphinx_design', + 'sphinx_copybutton', ] # Add any paths that contain templates here, relative to this directory. @@ -55,30 +47,64 @@ # produce any output in the built files. show_authors = True -# Keep warnings as “system message” paragraphs in the built documents. -# Regardless of this setting, warnings are always written to the standard error -# stream when sphinx-build is run. -keep_warnings = True - # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' - -html_theme_options = { - 'nosidebar': True, -} +html_theme = 'furo' +html_theme_options = {} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] +html_theme_options = { + "source_repository": "https://github.com/sphinx-notes/lilypond/", + "source_branch": "master", + "source_directory": "docs/", +} # The URL which points to the root of the HTML documentation. # It is used to indicate the location of document like canonical_url -html_baseurl = proj.__url__ +html_baseurl = 'https://sphinx.silverrainz.me/lilypond' html_logo = html_favicon = '_images/sphinx-notes.png' + +# -- Extensions ------------------------------------------------------------- + +extensions.append('sphinxnotes.any') +from sphinxnotes.any import Schema, Field as F +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 }}'), + # +] +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'), +} + +# -- 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('lilypond') + +# DOG FOOD CONFIGURATION START + +# DOG FOOD CONFIGURATION END diff --git a/docs/conf.rst b/docs/conf.rst new file mode 100644 index 0000000..2438e8d --- /dev/null +++ b/docs/conf.rst @@ -0,0 +1,47 @@ +============= +Configuration +============= + +.. hint:: Normally, extensions should work without any configuration + +: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']``) + 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 + +:lilypond_magick_home: (Type: ``str``, Default: ``None``) + Path to `ImageMagick`_ library. +: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']``. + + .. versionchanged:: 1.4 + + Add support for 'mp3' audio format + +:lilypond_audio_volume: (Type: ``int``, Default: `None`) + Volume of outputed audio, will be converted to value of `Timidity++`_ argument ``--volume``. + + .. versionadded:: 1.2 + +: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 `, will be converted to value of `CSS height`_. + + .. versionadded:: 1.1 + + +.. _LilyPond: https://lilypond.org/ +.. _FFmpeg: https://ffmpeg.org/ +.. _Timidity++: http://timidity.sourceforge.net/ +.. _ImageMagick: https://imagemagick.org/index.php +.. _CSS height: https://developer.mozilla.org/en-US/docs/Web/CSS/height diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..6d5d37f --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,159 @@ +======== +Examples +======== + +The LilyPond documentation used in example can be downloaded here: +:download:`/_scores/minuet-in-g.ly`. + +Original paper size +=================== + +.. code-block:: rst + + .. lilyinclude:: /_scores/minuet-in-g.ly + +.. lilyinclude:: /_scores/minuet-in-g.ly + +Paper without Footer and Edge +============================= + +.. code-block:: rst + + .. lilyinclude:: /_scores/minuet-in-g.ly + :nofooter: + :noedge: + +.. lilyinclude:: /_scores/minuet-in-g.ly + :nofooter: + :noedge: + +Smallest Paper Size +=================== + +.. code-block:: rst + + .. lilyinclude:: /_scores/minuet-in-g.ly + :noheader: + :nofooter: + :noedge: + +.. lilyinclude:: /_scores/minuet-in-g.ly + :noheader: + :nofooter: + :noedge: + +.. _example-audio-preview: + +Audio Preview +============= + +.. code-block:: rst + + .. lilyinclude:: /_scores/minuet-in-g.ly + :noheader: + :nofooter: + :noedge: + :audio: + +.. lilyinclude:: /_scores/minuet-in-g.ly + :noheader: + :nofooter: + :noedge: + :audio: + +.. _example-transposing: + +Transposing +=========== + +.. code-block:: rst + + .. lilyinclude:: /_scores/minuet-in-g.ly + :noheader: + :nofooter: + :noedge: + :audio: + :transpose: g c + +.. lilyinclude:: /_scores/minuet-in-g.ly + :noheader: + :nofooter: + :noedge: + :audio: + :transpose: g c + +Multiple Pages +============== + +.. code-block:: rst + + .. lilyinclude:: /_scores/alice.ly + :noedge: + :audio: + +.. lilyinclude:: /_scores/alice.ly + :noedge: + :audio: + +Loop +==== + +.. versionadded:: 1.2 + +.. code-block:: rst + + .. lilyinclude:: /_scores/minuet-in-g.ly + :noheader: + :nofooter: + :noedge: + :loop: + +.. lilyinclude:: /_scores/minuet-in-g.ly + :noheader: + :nofooter: + :noedge: + :loop: + +Control Bar at the Top +====================== + +.. versionadded:: 1.3 + +.. code-block:: rst + + .. lilyinclude:: /_scores/minuet-in-g.ly + :noheader: + :nofooter: + :noedge: + :controls: top + +.. lilyinclude:: /_scores/minuet-in-g.ly + :noheader: + :nofooter: + :noedge: + :controls: top + +Jianpu (Numbered Musical Notation) +================================== + +.. versionadded:: 1.5 + +.. code-block:: rst + + .. jianpu:: + + %% tempo: 4=60 + title=C Major Scale + 1=C + 2/4 + + 1 2 3 4 5 6 7 1' + +.. jianpu:: + + %% tempo: 4=60 + title=C Major Scale + 1=C + 2/4 + + 1 2 3 4 5 6 7 1' diff --git a/docs/index.rst b/docs/index.rst index 73a5046..fa9459a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,424 +1,125 @@ -.. sphinxnotes-lilypond documentation master file, created by - sphinx-quickstart on Sat Nov 28 00:42:50 2020. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. This file is generated from sphinx-notes/template. + You need to consider modifying the TEMPLATE or modifying THIS FILE. -============================= -Sphinx Extension for LilyPond -============================= +.. include:: ../README.rst -.. image:: https://img.shields.io/github/stars/sphinx-notes/lilypond.svg?style=social&label=Star&maxAge=2592000 - :target: https://github.com/sphinx-notes/lilypond +Introduction +============ -:version: |version| -:copyright: Copyright ©2020-2022 by Shengyu Zhang. -:copyright: Copyright ©2009 by Wei-Wei Guo. -:license: BSD, see LICENSE for details. +.. ADDITIONAL CONTENT START The extension is originated from `sphinx-contrib/lilypond`_ , allows `LilyPond`_ -music notes to be included in Sphinx-generated documents inline and outline. +music notes :lily:`\relative { c' }` to be included in Sphinx-generated documents. Compared to its predecessor, the extension has many new features such as: -- Scale `Transposing`_ -- `Audio Preview`_ +- Scale :ref:`example-transposing` +- :ref:`example-audio-preview` - Layout controlling -- LaTeX support (Since `2022-03-13 1.5`_) +- LaTeX support (Since :version:`1.5`) - And so on… .. _sphinx-contrib/lilypond: https://github.com/sphinx-contrib/lilypond .. _LilyPond: https://lilypond.org/ -.. contents:: - :local: - :backlinks: none - -Installation -============ +.. ADDITIONAL CONTENT END -Install the follwing runtime dependencies before using the extension: +Getting Started +=============== -- `LilyPond`_ -- `TiMidity++`_ -- `FFmpeg`_ -- `ImageMagick`_ +.. note:: -.. _FFmpeg: https://ffmpeg.org/ -.. _Timidity++: http://timidity.sourceforge.net/ -.. _ImageMagick: https://imagemagick.org/index.php + We assume you already have a Sphinx documentation, + if not, see `Getting Started with Sphinx`_. -Download it from official Python Package Index: +First, downloading extension from PyPI: .. code-block:: console $ pip install sphinxnotes-lilypond -Add extension to :file:`conf.py` in your sphinx project: +Then, add the extension name to ``extensions`` configuration item in your conf.py_: .. code-block:: python - extensions = [ - # … - 'sphinxnotes.lilypond', - # … - ] + extensions = [ + # … + 'sphinxnotes.lilypond', + # … + ] -Functionalities -=============== +.. _Getting Started with Sphinx: https://www.sphinx-doc.org/en/master/usage/quickstart.html +.. _conf.py: https://www.sphinx-doc.org/en/master/usage/configuration.html -Roles ------ +.. ADDITIONAL CONTENT START -.. _lily-role: - -The ``lily`` role -~~~~~~~~~~~~~~~~~ - -You can use ``lily`` role to insert short `LilyPond Music Expression`_ as inline -element. - -.. _LilyPond Music Expression: http://lilypond.org/doc/v2.19/Documentation/learning/music-expressions-explained - -For example: - -.. literalinclude:: ./lily-role-example.txt - :language: rst - -Will be rendered as: +Install the follwing runtime dependencies before using the extension: - .. include:: ./lily-role-example.txt +- `LilyPond`_ +- `TiMidity++`_ +- `FFmpeg`_ +- `ImageMagick`_ .. note:: + + A basic understanding of Lilypond notation is required, or you can refer to + `LilyPond Learning Manual`_. - Role ``lily`` produces a preview image of the music expression (using - ``-dpreview=#t``). You can still write a long music expression as interpreted text, - but only the beginning can be shown. - -Directives ----------- - -.. _lily-directive: - -The ``lily`` directive -~~~~~~~~~~~~~~~~~~~~~~ - -The ``lily`` directive is used to insert a complete LilyPond score as -block level element. - -.. literalinclude:: ./lily-directive-example.txt - :language: rst - -Will be rendered as: - - .. include:: ./lily-directive-example.txt - -The directive supports the following options: - -:noheader: (flag) - Whether to remove the header of score -:nofooter: (flag) - Whether to remove the footer of score -:noedge: (flag) - Whether to remove the blank edges of score -:audio: (flag) - Whether to show a audio player for listen LilyPond-generated MIDI file -:loop: (flag) - Whethre audio player will automatically seek back to the start upon reaching the end of the audio. - This implies ``audio``. - - .. versionadded:: 1.2 - -:transpose: (text) - Transposing the pitches of score from one to another. - Pitches are written in `LilyPond Notation`_ and separated in whitespace. - For example: ``:transpose: c' d'`` - - .. _LilyPond Notation: http://lilypond.org/doc/v2.18/Documentation/notation/writing-pitches - -:controls: (text, one of the ``top`` or ``bottom``) - Specify the position of the control bar relative to the score. - This implies ``audio``. - - .. versionadded:: 1.3 - -The ``lilyinclude`` directives -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``lilyinclude`` directive is similar to :ref:`lily-directive`, -except the source of LilyPond are read from file but not contents of directive. - -.. literalinclude:: ./lilyinclude-directive-example.txt - :language: rst - -Will be rendered as: - - .. include:: ./lilyinclude-directive-example.txt - -Options of the directive are same to :ref:`lily-directive`. - -.. seealso:: - - You and download the example LilyPond documentation from here: - :download:`witch-spring.ly`. +.. _FFmpeg: https://ffmpeg.org/ +.. _Timidity++: http://timidity.sourceforge.net/ +.. _ImageMagick: https://imagemagick.org/index.php +.. _LilyPond Learning Manual: https://lilypond.org/doc/Documentation/learning/index -Configuration -============= +We provide :ref:`roles` for embedding score fragment and :ref:`directives` for +embedding a whole socre: -.. hint:: Normally, extensions can work without any configuration +.. grid:: 2 -: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']``) - 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. + .. grid-item-card:: Role - .. versionadded:: 1.4 + .. literalinclude:: /_scores/lily-role.txt + :language: rst -:lilypond_magick_home: (Type: ``str``, Default: ``None``) - Path to `ImageMagick`_ library. -: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']``. + .. grid-item-card:: Result - .. versionchanged:: 1.4 + .. include:: /_scores/lily-role.txt - Add support for 'mp3' audio format +.. grid:: 2 -:lilypond_audio_volume: (Type: ``int``, Default: `None`) - Volume of outputed audio, will be converted to value of `Timidity++`_ argument ``--volume``. + .. grid-item-card:: Directive - .. versionadded:: 1.2 + .. literalinclude:: /_scores/lily-directive-c-major-scale.txt + :language: rst -:lilypond_png_resolution: (Type: ``int``, Default: ``300``) - Resolution in DPI of score in PNG format, will be converted to value of LilyPond_ argument ``-dresolution``. + .. grid-item-card:: Result - .. versionadded:: 1.1 - -:lilypond_inline_score_size: (Type: ``str``, Default: ``2.5em``) - Line height of :ref:`inline socre `, will be converted to value of `CSS height`_. + .. include:: /_scores/lily-directive-c-major-scale.txt - .. versionadded:: 1.1 +See :doc:`usage` for more details. -.. _CSS height: https://developer.mozilla.org/en-US/docs/Web/CSS/height +.. ADDITIONAL CONTENT END -Examples +Contents ======== -The LilyPond documentation used in example can be downloaded here: -:download:`/minuet-in-g.ly`. - -Original paper size -------------------- - -.. code-block:: rst - - .. lilyinclude:: minuet-in-g.ly - - -.. lilyinclude:: minuet-in-g.ly - -Paper without Footer and Edge ------------------------------ - -.. code-block:: rst - - .. lilyinclude:: minuet-in-g.ly - :nofooter: - :noedge: - -.. lilyinclude:: minuet-in-g.ly - :nofooter: - :noedge: - -Smallest Paper Size -------------------- - -.. code-block:: rst - - .. lilyinclude:: minuet-in-g.ly - :noheader: - :nofooter: - :noedge: - -.. lilyinclude:: minuet-in-g.ly - :noheader: - :nofooter: - :noedge: - -Audio Preview -------------- - -.. code-block:: rst - - .. lilyinclude:: minuet-in-g.ly - :noheader: - :nofooter: - :noedge: - :audio: - -.. lilyinclude:: minuet-in-g.ly - :noheader: - :nofooter: - :noedge: - :audio: - -Transposing ------------- - -.. code-block:: rst - - .. lilyinclude:: minuet-in-g.ly - :noheader: - :nofooter: - :noedge: - :audio: - :transpose: g c - -.. lilyinclude:: minuet-in-g.ly - :noheader: - :nofooter: - :noedge: - :audio: - :transpose: g c - -Multiple Pages --------------- - -.. code-block:: rst - - .. lilyinclude:: alice.ly - :noedge: - :audio: - -.. lilyinclude:: alice.ly - :noedge: - :audio: - -Loop ----- - -.. versionadded:: 1.2 - -.. code-block:: rst - - .. lilyinclude:: minuet-in-g.ly - :noheader: - :nofooter: - :noedge: - :loop: - -.. lilyinclude:: minuet-in-g.ly - :noheader: - :nofooter: - :noedge: - :loop: - -Control Bar at the Top ----------------------- - -.. versionadded:: 1.3 - -.. code-block:: rst - - .. lilyinclude:: minuet-in-g.ly - :noheader: - :nofooter: - :noedge: - :controls: top - -.. lilyinclude:: minuet-in-g.ly - :noheader: - :nofooter: - :noedge: - :controls: top - -Jianpu (Numbered Musical Notation) -================================== - -.. versionadded:: 1.5 - -.. code-block:: rst - - .. jianpu:: - - %% tempo: 4=60 - title=C Major Scale - 1=C - 2/4 - - 1 2 3 4 5 6 7 1' - -.. jianpu:: - - %% tempo: 4=60 - title=C Major Scale - 1=C - 2/4 - - 1 2 3 4 5 6 7 1' - -Chang Log -========= - -2022-10-08 1.6 --------------- - -- Fix resolution of SVG output (#18) -- Add basic Jianpu (Numbered Musical Notation) support (#17) -- Don't panic when running unsupported builders (#20) - -2022-03-13 1.5 --------------- - -- Add LaTeX builder suppport - -2021-12-19 1.4 --------------- - -- Note ly files as dependencies, so Sphinx will rebuild document when ly file changes -- Won't crash when score file does not exist -- Left a "system message" paragraphs when score build failed -- Add support for MP3 audio format, FFmpeg_ is required - -2021-11-07 1.3 --------------- - -- Add ``controls`` flag for specifing the position of the control bar - -2021-09-17 1.2 --------------- - -- Simplify argument passing between lilypond binding and sphinx extension -- Add ``loop`` flag for directives -- Add confval ``lilypond_audio_volume`` - -2021-09-12 1.1 --------------- - -* 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 ` -* Stop using ``
`` as container of block-level score, which is buggy on Safari - -2021-06-26 1.0 --------------- - -* Rebuild env when configuration changed -* Fix wrong license value +.. toctree:: + :caption: Contents -2020-12-27 1.0a2 ----------------- + usage + examples + conf + changelog -* Support multiple pages documents -* Imporve of lilypond outputs cache +The Sphinx Notes Project +======================== -2020-12-26 1.0a1 ----------------- +This project is a developed by `Shengyu Zhang`__, +as part of **The Sphinx Notes Project**. -* Fix invalid insertion of ``\header`` -* Set default audio format to wav +.. toctree:: + :caption: The Sphinx Notes Project -2020-12-06 1.0a0 ----------------- + Home + Blog + PyPI -The alpha version is out, enjoy~ +__ https://github.com/SilverRainZ diff --git a/docs/lilyinclude-directive-example.txt b/docs/lilyinclude-directive-example.txt deleted file mode 100644 index 782702c..0000000 --- a/docs/lilyinclude-directive-example.txt +++ /dev/null @@ -1,4 +0,0 @@ -.. lilyinclude:: ./witch-spring.ly - :nofooter: - :noedge: - :audio: diff --git a/docs/make.bat b/docs/make.bat index 2119f51..b3cafbd 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -1,3 +1,5 @@ +REM This file is generated from sphinx-notes/template. DO NOT EDIT. + @ECHO OFF pushd %~dp0 @@ -5,7 +7,7 @@ pushd %~dp0 REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build + set SPHINXBUILD=python -msphinx ) set SOURCEDIR=. set BUILDDIR=_build @@ -15,21 +17,21 @@ if "%1" == "" goto help %SPHINXBUILD% >NUL 2>NUL if errorlevel 9009 ( echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. + echo.The Sphinx module was not found. Make sure you have Sphinx installed, + echo.then set the SPHINXBUILD environment variable to point to the full + echo.path of the 'sphinx-build' executable. Alternatively you may add the + echo.Sphinx directory to PATH. echo. echo.If you don't have Sphinx installed, grab it from echo.http://sphinx-doc.org/ exit /b 1 ) -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% goto end :help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% :end popd diff --git a/docs/minuet-in-g.png b/docs/minuet-in-g.png deleted file mode 100644 index 6970bcf..0000000 Binary files a/docs/minuet-in-g.png and /dev/null differ diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..0319807 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,102 @@ +===== +Usage +===== + +.. _roles: + +Roles +===== + +.. _lily-role: + +The ``lily`` role +----------------- + +You can use ``lily`` role to insert short `LilyPond Music Expression`_ as inline +element. + +.. _LilyPond Music Expression: http://lilypond.org/doc/v2.19/Documentation/learning/music-expressions-explained + +For example: + +.. literalinclude:: /_scores/lily-role.txt + :language: rst + +Will be rendered as: + + .. include:: /_scores/lily-role.txt + +.. note:: + + Role ``lily`` produces a preview image of the music expression (using + ``-dpreview=#t``). You can still write a long music expression as interpreted text, + but only the beginning can be shown. + +.. _directives: + +Directives +========== + +.. _lily-directive: + +The ``lily`` directive +---------------------- + +The ``lily`` directive is used to insert a complete LilyPond score as +block level element. + +.. literalinclude:: /_scores/lily-directive.txt + :language: rst + +Will be rendered as: + + .. include:: /_scores/lily-directive.txt + +The directive supports the following options: + +:noheader: (flag) + Whether to remove the header of score +:nofooter: (flag) + Whether to remove the footer of score +:noedge: (flag) + Whether to remove the blank edges of score +:audio: (flag) + Whether to show a audio player for listen LilyPond-generated MIDI file +:loop: (flag) + Whethre audio player will automatically seek back to the start upon reaching the end of the audio. + This implies ``audio``. + + .. versionadded:: 1.2 + +:transpose: (text) + Transposing the pitches of score from one to another. + Pitches are written in `LilyPond Notation`_ and separated in whitespace. + For example: ``:transpose: c' d'`` + + .. _LilyPond Notation: http://lilypond.org/doc/Documentation/notation/writing-pitches + +:controls: (text, one of the ``top`` or ``bottom``) + Specify the position of the control bar relative to the score. + This implies ``audio``. + + .. versionadded:: 1.3 + +The ``lilyinclude`` directive +----------------------------- + +The ``lilyinclude`` directive is similar to :ref:`lily-directive`, +except the source of LilyPond are read from file but not contents of directive. + +.. literalinclude:: /_scores/lilyinclude-directive.txt + :language: rst + +Will be rendered as: + + .. include:: /_scores/lilyinclude-directive.txt + +Options of the directive are same to :ref:`lily-directive`. + +.. seealso:: + + You and download the example LilyPond documentation from here: + :download:`/_scores/witch-spring.ly`. diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..1074bc5 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,62 @@ +# This file is generated from sphinx-notes/template. +# You need to consider modifying the TEMPLATE or modifying THIS FILE. + +# This file is used to configure your project. +# Read more about the various options under: +# https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#declaring-project-metadata + +[project] +name = "sphinxnotes-lilypond" +description = "Sphinx extension for embedding LilyPond scores" +readme = "README.rst" +license = { file = "BSD-3-Clause" } +authors = [ { name = "Shengyu Zhang" } ] +maintainers = [ { name = "Shengyu Zhang" } ] +keywords = ["sphinx", "extension", "documentation", "music", "lilypond"] # TOOD: additional_keywords +classifiers = [ + # "Development Status :: 4 - Beta", + "Environment :: Plugins", + "Framework :: Sphinx", + "Framework :: Sphinx :: Extension", + "License :: OSI Approved :: BSD License", + "Operating System :: OS Independent", + "Programming Language :: Python", + "Programming Language :: Python :: 3", + "Topic :: Documentation", + "Topic :: Documentation :: Sphinx", +] + +requires-python = ">=3.8" +dependencies = [ + "Sphinx>=4", + "python-ly==0.9", + "Wand==0.6", +] + +dynamic = ["version"] # required by setuptools_scm, see section [build-system] + +[project.optional-dependencies] +docs = ["furo", "sphinxnotes-any", "sphinx_design", "sphinx_copybutton"] +test = ["pytest"] +dev = ["build", "twine", "cruft"] + +[project.urls] +homepage = "https://sphinx.silverrainz.me/lilypond" +documentation = "https://sphinx.silverrainz.me/lilypond" +repository = "https://github.com/sphinx-notes/lilypond" +changelog = "https://sphinx.silverrainz.me/lilypond/changelog.html" +tracker = "https://github.com/sphinx-notes/lilypond/issues" + +[build-system] +requires = ["setuptools>=46.1.0", "setuptools_scm[toml]>=5", "wheel"] +build-backend = "setuptools.build_meta" + +[tool.setuptools_scm] +# For smarter version schemes and other configuration options, +# check out https://github.com/pypa/setuptools_scm +version_scheme = "no-guess-dev" + +[tool.setuptools.packages.find] +# Find namespace package, +# check out https://setuptools.pypa.io/en/latest/userguide/package_discovery.html#finding-namespace-packages +where = ["src"] diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index a87ab4b..0000000 --- a/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -python-ly==0.9 -Wand==0.6 diff --git a/setup.py b/setup.py deleted file mode 100644 index 5e595b6..0000000 --- a/setup.py +++ /dev/null @@ -1,44 +0,0 @@ -# -*- coding: utf-8 -*- - -from setuptools import setup, find_packages -import sys -import os -sys.path.insert(0, os.path.abspath('./sphinxnotes')) -import lilypond as proj - -with open('README.rst') as f: - long_desc = f.read() - -setup( - name=proj.__title__, - version=proj.__version__, - url=proj.__url__, - download_url='http://pypi.python.org/pypi/' + proj.__title__, - license=proj.__license__, - author=proj.__author__, - description=proj.__description__, - long_description=long_desc, - long_description_content_type = 'text/x-rst', - zip_safe=False, - classifiers=[ - 'Development Status :: 5 - Production/Stable', - 'Environment :: Console', - 'Environment :: Web Environment', - 'Environment :: Plugins', - 'Framework :: Sphinx :: Extension', - 'Intended Audience :: Developers', - 'License :: OSI Approved :: BSD License', - 'Operating System :: OS Independent', - 'Programming Language :: Python', - 'Topic :: Documentation', - 'Topic :: Utilities', - ], - keywords=proj.__keywords__, - platforms='any', - python_requires='>=3', - packages=find_packages(), - include_package_data=True, - # sphinx.util.compat.Directive class is now deprecated in 1.6 - install_requires= ['Sphinx>=1.6', 'python-ly', 'wand'], - namespace_packages=['sphinxnotes'], -) diff --git a/sphinxnotes/__init__.py b/sphinxnotes/__init__.py deleted file mode 100644 index 5427c41..0000000 --- a/sphinxnotes/__init__.py +++ /dev/null @@ -1,15 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinxnotes - ~~~~~~~~~~~ - - This package is a namespace package that contains all extensions - distributed in the ``sphinx-notes`` distribution. - - :copyright: Copyright 2020 by the Shengyu Zhang. - :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. - :license: BSD, see LICENSE for details. -""" - -__import__('pkg_resources').declare_namespace(__name__) - diff --git a/sphinxnotes/lilypond/jianpu.py b/sphinxnotes/lilypond/jianpu.py deleted file mode 120000 index f209b02..0000000 --- a/sphinxnotes/lilypond/jianpu.py +++ /dev/null @@ -1 +0,0 @@ -../../jianpu-ly/jianpu-ly.py \ No newline at end of file diff --git a/sphinxnotes/lilypond/__init__.py b/src/sphinxnotes/lilypond/__init__.py similarity index 100% rename from sphinxnotes/lilypond/__init__.py rename to src/sphinxnotes/lilypond/__init__.py diff --git a/src/sphinxnotes/lilypond/jianpu.py b/src/sphinxnotes/lilypond/jianpu.py new file mode 120000 index 0000000..8b7d534 --- /dev/null +++ b/src/sphinxnotes/lilypond/jianpu.py @@ -0,0 +1 @@ +../../../jianpu-ly/jianpu-ly.py \ No newline at end of file diff --git a/sphinxnotes/lilypond/lilypond.py b/src/sphinxnotes/lilypond/lilypond.py similarity index 100% rename from sphinxnotes/lilypond/lilypond.py rename to src/sphinxnotes/lilypond/lilypond.py