.rst .pdf

repository open issue suggest edit

Sphinx

Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档 就是由Sphinx生成的， 并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持. 本站当然也是使用 Sphinx 生成的，它采用reStructuredText! Sphinx还在继续开发.

重要

1. Sphinx 的 4.1.2 版文档 (OSGeo)

2. Sphinx 的官方文档 （Created using Sphinx 5.0.0+）

警告

需要注意的是，在本篇章笔记中记录的知识部分语法；更多详细全面的语法请前往上文提供的官方文档中学习。

Sphinx and reStructureText 笔记目录

• 1. 准备
  • 1.1. 安装 Sphinx 并下载必要的包
  • 1.2. 在项目根目录运行生成文档命令 sphinx-quickstart
  • 1.3. 配置主题
  • 1.4. 通过vscode的git插件创建存储库
  • 1.5. 推送
  • 1.6. 不同文件下的 tab 键行为控制
• 2. reStructureText 语法学习
  • 2.1. 标题学习
    • 2.1.1. 推荐标题分级
    • 2.1.2. title-directive / title指令
  • 2.2. 基础杂糅
    • 2.2.1. 字段列表
    • 2.2.2. 文字块 ::
    • 2.2.3. 注释
    • 2.2.4. 脚注/尾注
    • 2.2.5. 索引
    • 2.2.6. 列表
  • 2.3. 指令
    • 2.3.1. epigraph 题词
    • 2.3.2. hlist
    • 2.3.3. glossary
    • 2.3.4. topic / 主题 or 总论
    • 2.3.5. 目录
    • 2.3.6. sidebar 边注栏
    • 2.3.7. image 与 figure
    • 2.3.8. figure
    • 2.3.9. HTML细节
    • 2.3.10. 替代指令 replace
  • 2.4. 表格
    • 2.4.1. Grid Table
  • 2.5. 表格指令
    • 2.5.1. table(directive)
    • 2.5.2. csv-table
    • 2.5.3. list-table
  • 2.6. 使用文件
    • 2.6.1. include 指令
  • 2.7. 代码显示
    • 2.7.1. 使用codeblock
    • 2.7.2. 为代码块添加标题和 label
    • 2.7.3. 显示行号
    • 2.7.4. 突出特定行
    • 2.7.5. 引用一个文件 literalinclude
    • 2.7.6. 指定引用文件的方法，或类
    • 2.7.7. diff2个文件
    • 2.7.8. 锚点小测试
  • 2.8. 角色
    • 2.8.1. 交叉引用任意位置 / 锚
    • 2.8.2. 引用可下载文件
    • 2.8.3. 交叉引用文档
    • 2.8.4. 数学
    • 2.8.5. raw
    • 2.8.6. 其他语义标记
  • 2.9. 域
  • 2.10. 推荐文章形式
    • 2.10.1. 软件技术行业的发展现状
    • 2.10.2. 软件技术行业的人才需求状况
    • 2.10.3. 岗位（岗位群）调查
    • 2.10.4. 结论
  • 2.11. 文章类笔记推荐写法
    • 2.11.1. 推荐文章写法的代码
    • 2.11.2. 标题之间的分隔
• 3. Markdown 支持
  • 3.1. MyST Markdown
• 4. 配置
  • 4.1. .readthedocs.yaml
  • 4.2. requirement.txt
  • 4.3. conf.py
• 5. HTML Theme
  • 5.1. sphinx_rtd_theme 主题配置
  • 5.2. sphinx_book_theme 主题配置

上一页

A Sphinx Book Template

下一页

1. 准备部分