Sphinx-Autobuild 开源项目教程

Sphinx-Autobuild 开源项目教程

sphinx-autobuildWatch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.项目地址:https://gitcode.com/gh_mirrors/sp/sphinx-autobuild

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

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

sphinx-autobuild/
├── .github/
│   └── workflows/
│       └── ci.yml
├── sphinx_autobuild/
│   ├── __init__.py
│   ├── cmdline.py
│   └── server.py
├── tests/
│   ├── __init__.py
│   ├── test_cmdline.py
│   └── test_server.py
├── .gitignore
├── LICENSE
├── README.md
├── pyproject.toml
└── setup.cfg

目录结构介绍

• .github/workflows/ci.yml: GitHub Actions 的持续集成配置文件。
• sphinx_autobuild/: 项目的主要代码目录。
  • __init__.py: 模块初始化文件。
  • cmdline.py: 命令行接口实现文件。
  • server.py: 自动构建服务器实现文件。
• tests/: 测试代码目录。
  • __init__.py: 测试模块初始化文件。
  • test_cmdline.py: 命令行接口的测试文件。
  • test_server.py: 自动构建服务器的测试文件。
• .gitignore: Git 忽略文件配置。
• LICENSE: 项目许可证。
• README.md: 项目说明文档。
• pyproject.toml: 项目构建配置文件。
• setup.cfg: 项目安装配置文件。

2. 项目的启动文件介绍

项目的启动文件是 sphinx_autobuild/cmdline.py。这个文件定义了命令行接口，用户可以通过命令行启动 Sphinx-Autobuild 服务。

启动文件介绍

• cmdline.py: 该文件包含了 main 函数，负责解析命令行参数并启动自动构建服务器。

def main():
    parser = argparse.ArgumentParser(description="Sphinx autobuild")
    parser.add_argument("source", nargs="?", default=".", help="source directory")
    parser.add_argument("build", nargs="?", default="_build/html", help="build directory")
    parser.add_argument("--port", type=int, default=8000, help="port to serve on")
    parser.add_argument("--host", default="127.0.0.1", help="host to serve on")
    parser.add_argument("--ignore", action="append", default=[], help="files to ignore")
    parser.add_argument("--pre-build", help="command to run before building")
    parser.add_argument("--open-browser", action="store_true", help="open browser on startup")
    parser.add_argument("--delay", type=float, default=0, help="delay before reloading")
    args = parser.parse_args()

    server = LiveReloadServer(
        builder=SphinxBuilder(args.source, args.build, args.ignore, args.pre_build),
        host=args.host,
        port=args.port,
        delay=args.delay,
    )
    if args.open_browser:
        webbrowser.open(f"http://{args.host}:{args.port}")
    try:
        server.watch(args.source)
        server.serve()
    except KeyboardInterrupt:
        pass

3. 项目的配置文件介绍

项目的配置文件主要包括 pyproject.toml 和 setup.cfg。

配置文件介绍

• pyproject.toml: 该文件定义了项目的构建系统和依赖管理。

[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

• setup.cfg: 该文件包含了项目的元数据和安装配置。

[metadata]
name = sphinx-autobuild
version = 2021
description = Rebuild Sphinx documentation on changes, with live-reload in the browser
author = Executable Books
author_email = contact@executablebooks.org
url = https://github.com/executablebooks/sphinx-autobuild
license = MIT
long_description = file: README.md
long

sphinx-autobuildWatch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.项目地址:https://gitcode.com/gh_mirrors/sp/sphinx-autobuild