Sphinx-Gallery 项目教程

Sphinx-Gallery 项目教程

sphinx-gallery Sphinx extension for automatic generation of an example gallery 项目地址: https://gitcode.com/gh_mirrors/sp/sphinx-gallery

1. 项目的目录结构及介绍

Sphinx-Gallery 项目的目录结构如下：

sphinx-gallery/
├── docs/
│   ├── conf.py
│   ├── index.rst
│   └── ...
├── sphinx_gallery/
│   ├── __init__.py
│   ├── backreferences.py
│   ├── ...
├── examples/
│   ├── plot_example.py
│   └── ...
├── setup.py
├── README.rst
└── ...

目录结构介绍：

• docs/: 包含 Sphinx 文档的配置文件和文档源文件。
• sphinx_gallery/: 包含 Sphinx-Gallery 的核心代码，包括各种功能模块。
• examples/: 包含示例脚本，这些脚本会被自动生成到示例画廊中。
• setup.py: 项目的安装脚本。
• README.rst: 项目的介绍文件。

2. 项目的启动文件介绍

Sphinx-Gallery 项目没有传统意义上的“启动文件”，因为它是一个 Sphinx 扩展，通常在构建 Sphinx 文档时自动运行。不过，核心的启动逻辑在 sphinx_gallery/__init__.py 文件中定义。

sphinx_gallery/__init__.py 文件介绍：

• 该文件包含了 Sphinx-Gallery 的主要入口点，定义了如何处理和生成示例画廊。
• 它初始化了 Sphinx 扩展，并注册了必要的钩子函数，以便在 Sphinx 构建过程中执行。

3. 项目的配置文件介绍

Sphinx-Gallery 的配置主要在 Sphinx 文档的 conf.py 文件中进行。

docs/conf.py 文件介绍：

• extensions: 需要添加 sphinx_gallery.gen_gallery 扩展。

  extensions = [
      'sphinx.ext.autodoc',
      'sphinx.ext.intersphinx',
      'sphinx_gallery.gen_gallery',
  ]
  

• sphinx_gallery_conf: 配置示例画廊的参数，如示例脚本的路径、生成画廊的样式等。

  sphinx_gallery_conf = {
      'examples_dirs': '../examples',  # 示例脚本的路径
      'gallery_dirs': 'auto_examples',  # 生成画廊的路径
      'filename_pattern': r'.*\.py',    # 匹配的文件名模式
  }
  

通过以上配置，Sphinx-Gallery 可以自动生成示例画廊，并将其集成到 Sphinx 文档中。

sphinx-gallery Sphinx extension for automatic generation of an example gallery 项目地址: https://gitcode.com/gh_mirrors/sp/sphinx-gallery