docs.gl 项目教程

1. 项目目录结构及介绍

docs.gl 是一个用于生成 OpenGL 参考文档的 Python 项目。以下是项目的目录结构及其介绍：

docs.gl/
├── github/workflows/
├── el3/
├── sl4/
├── es1/
├── es2/
├── es3/
├── gl2/
├── gl3/
├── gl4/
├── html/
├── htmlmin/
├── specs/
├── .gitignore
├── .gitmodules
├── build.bat
├── build_full.bat
├── compile.py
├── docs.gl.psd
├── docs.gl16.psd
├── find_glsl.py
├── glsl.py
├── glsl_spec.py
├── insert_additional.py
├── make_copyright.py
├── opengl.py
├── opengl_spec.py
├── read_glsl_spec.py
├── read_spec.py
├── README.md
├── server.py
├── server.sh
├── shared.py
├── shared_glsl.py
├── start_offline_webserver.py
├── strip.py
├── TODO.md
└── htdocs/

目录结构介绍

• github/workflows/: 包含 GitHub Actions 的工作流配置文件。
• el3/, sl4/, es1/, es2/, es3/, gl2/, gl3/, gl4/: 这些目录包含 OpenGL 和 GLSL 命令的手册页，每个目录对应不同的 OpenGL 版本。
• html/: 包含用于编译站点的模板文件和其他资源。
• htmlmin/: 包含 HTML 文件的压缩版本。
• specs/: 包含 OpenGL 规范的 XML 文件。
• .gitignore, .gitmodules: Git 配置文件。
• build.bat, build_full.bat: Windows 下的构建脚本。
• compile.py: 主要的 Python 脚本，用于读取和处理手册页并生成静态 HTML。
• docs.gl.psd, docs.gl16.psd: 项目的 PSD 文件。
• find_glsl.py, glsl.py, glsl_spec.py, insert_additional.py, make_copyright.py, opengl.py, opengl_spec.py, read_glsl_spec.py, read_spec.py, server.py, server.sh, shared.py, shared_glsl.py, start_offline_webserver.py, strip.py: 这些是辅助 Python 脚本，用于处理手册页、生成规范数据、启动本地服务器等。
• README.md, TODO.md: 项目的说明文件和待办事项。
• htdocs/: 包含编译后的静态 HTML 文件，用于部署网站。

2. 项目启动文件介绍

项目的启动文件是 compile.py，它是一个 Python 脚本，用于读取和处理 OpenGL 手册页并生成静态 HTML 文件。以下是启动文件的详细介绍：

compile.py

compile.py 是项目的核心脚本，负责以下任务：

• 读取每个手册页并进行处理。
• 生成静态 HTML 文件。
• 支持不同的构建选项，如 --full 和 --local-assets。

使用方法

python compile.py

• --full: 使用 HTML 压缩和 Unicode 处理进行完整构建。
• --local-assets: 下载字体和 JavaScript 库，并使用本地副本构建 HTML 和 CSS。

3. 项目配置文件介绍

项目中没有传统的配置文件，但可以通过以下方式进行配置：

构建脚本

• build.bat: Windows 下的构建脚本，用于简化构建过程。
• build_full.bat: 用于完整构建的 Windows 脚本。

模板文件

• html/ 目录下的文件是模板文件，用于进一步处理手册页。模板文件中包含一些标记（如 [$current_api]），这些标记在编译过程中会被动态替换。

辅助脚本

• opengl.py, glsl.py: 包含辅助表，指定哪些命令出现在哪些版本中，以及哪些示例应该出现在哪些页面上。
• insert_additional.py, make_copyright.py, strip.py: 这些脚本用于处理手册页，可以用于额外的处理。

通过这些文件和脚本，可以对项目进行定制和配置，以满足特定的需求。