abc-sphinx

abc代码渲染扩展,适用于sphinx渲染乐谱代码.

• 已经实现在rst文件内解析.. abc::代码段, 并渲染成乐谱图片.
• 已经实现在Markdown文件内解析```abc代码段, 并渲染成乐谱图片.

docs目录下有示例代码.

安装

安装系统依赖:(Ubuntu)

sudo apt-get install abcm2ps

其他系统使用相应的安装工具安装abcm2ps 在.readthedocs.yaml文档中要添加以下内容：

build:
  apt_packages:
    - abcm2ps

安装abcSphinx扩展:

pip install abcSphinx

使用

在conf.py中添加以下内容：

extensions = [
    'abcSphinx'
]

然后在rst文件中使用以下语法：

.. abc::

    X: 1
    T: 欢乐颂
    C: Ludwig van Beethoven, elfin
    S: Copyright 2005, elfin
    M: 4/4
    L: 1/8
    Q: 1/4=80
    K: C
    | E2 E2 F2 G2 | G2 F2 E2 D2 | C2 C2 D2 E2 | E2-ED Dz z2 |
    | E2 E2 F2 G2 | G2 F2 E2 D2 | C2 C2 D2 E2 | D2-DC C2 z2 |
    | D2 D2 E2 C2 | D2 EF E2 C2 | D2 EF E2 D2 | C2 D2 _G2 z2 |
    | E2 E2 F2 G2 | G2 F2 E2 D2 | C2 C2 D2 E2 | D2-DC C2 z2 |

注意在rst文件中，.. abc::下一行要接一个空行, 否则代码段不识别。

sphinx案例

快速搭建一个sphinx项目：

$ sphinx-quickstart docs
欢迎使用 Sphinx 8.2.3 快速配置工具。

请输入接下来各项设定的值（如果方括号中指定了默认值，直接
按回车即可使用默认值）。

已选择根路径：docs

有两种方式来设置用于放置 Sphinx 输出的构建目录：
一是在根路径下创建“_build”目录，二是在根路径下创建“source”
和“build”两个独立的目录。
> 独立的源文件和构建目录（y/n） [n]: y

项目名称将会出现在文档的许多地方。
> 项目名称: abc-test
> 作者名称: elfin
> 项目发行版本 []: 1.0

如果用英语以外的语言编写文档，
你可以在此按语言代码选择语种。
Sphinx 会把内置文本翻译成相应语言的版本。

支持的语言代码列表见：
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language。
> 项目语种 [en]: zh_CN

正在创建文件 /Users/elfin/project/abc-test/docs/source/conf.py。
正在创建文件 /Users/elfin/project/abc-test/docs/source/index.rst。
正在创建文件 /Users/elfin/project/abc-test/docs/Makefile。
正在创建文件 /Users/elfin/project/abc-test/docs/make.bat。

完成：已创建初始目录结构。

书写rst文件：

在source文件夹内写music/music.rst文件，内容如下：

music test in rst
=========================


.. abc::
    
    X: 1
    T: 欢乐颂
    C: Ludwig van Beethoven, elfin
    S: Copyright 2005, elfin
    M: 4/4
    L: 1/8
    Q: 1/4=80
    K: C
    | E2 E2 F2 G2 | G2 F2 E2 D2 | C2 C2 D2 E2 | E2-ED Dz z2 |
    | E2 E2 F2 G2 | G2 F2 E2 D2 | C2 C2 D2 E2 | D2-DC C2 z2 |
    | D2 D2 E2 C2 | D2 EF E2 C2 | D2 EF E2 D2 | C2 D2 _G2 z2 |
    | E2 E2 F2 G2 | G2 F2 E2 D2 | C2 C2 D2 E2 | D2-DC C2 z2 |

在index.rst文件中添加以下内容：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

    music/music

配置conf.py文件：

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'abc-test'
copyright = '2025, elfin'
author = 'elfin'
release = '1.3'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    'abcSphinx'
]

templates_path = ['_templates']
exclude_patterns = []

language = 'zh_CN'

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
# html_extra_path = ['_abc_images']  # 配置项

abc_global_classes = ["music-sheet", "responsive"]
abc_force_rebuild = True 

构建文档：

$ cd docs
$ make clean html

查看效果：

$ cd docs/build/html
$ python -m http.server 8000

打开浏览器，访问