Sphinx入门指南

引言

• Sphinx是什么?

• A: Sphinx是一个自动生成文档的工具，可以用简洁的语法快速生成优雅的文档。

• 哪些场景要用Sphinx?

• A: 如果想要写书，不想陷入复杂的排版中，可以考虑使用这个。如果有代码项目之类的，可以用它快速生成使用文档，支持markdown语法。

使用步骤

1. 安装sphinx: pip install sphinx

2. 创建demo: sphinx-quickstart，根据提示输入项目名称、作者、版本号、语言等信息

   • Separate source and build directories (y/n) [n]: y <--------这里选y表示编译的文件单独放在build

3. 项目文件结构：

   • build：生成的文件的输出目录
   • source: 存放文档源文件
   • • _static：静态文件目录，比如图片等
     • _templates：模板目录
     • conf.py：进行 Sphinx 的配置，如主题配置等
     • index.rst：文档项目起始文件，用于配置文档的显示结构
   • cmd.bat：这是自己加的脚本文件（里面的内容是‘cmd.exe’）,用于快捷的打开windows的命令行
   • make.bat：Windows 命令行中编译用的脚本
   • Makefile：编译脚本，make 命令编译时用

4. 编译html:

   # 在source build目录下执行
   make html
   

5. 更改样式主题：

   • 安装sphinx_rtd_theme: pip install sphinx_rtd_theme

   • 更改config.py:

     html_theme = 'sphinx_rtd_theme'
     

6. 安装markdown支持工具

   pip install myst-parser
   

7. 安装支持mermaid渲染工具:pip install sphinxcontrib.mermaid

   ```{mermaid}  # 这里需要{}包裹
   graph LR
     a --> b
   ```
   

8. 配置config.py

   project = 'Test'
   copyright = '2023,'
   author = 'Test'
   release = 'v2.1.3'
   repo_url = 'www.baidu.com'
   
   extensions = [
       'myst_parser',
       "sphinxcontrib.mermaid",
       "sphinx_copybutton",  # 复制按钮
   ]
   
   source_suffix = {
       '.rst': 'restructuredtext',
       '.txt': 'markdown',
       '.md': 'markdown',
   }
   
   myst_enable_extensions = [
       "tasklist",
       "deflist",
       "dollarmath",
       # "colon_fence"  # 支持colons
   ]
   
   templates_path = ['_templates']
   exclude_patterns = []
   
   language = 'zh_CN'
   
   html_theme = 'sphinx_rtd_theme'
   html_theme_options = {
       'analytics_anonymize_ip': False,
       'logo_only': True,
       'display_version': True,
       'prev_next_buttons_location': 'bottom',
       'style_external_links': False,
       'collapse_navigation': True,
       'sticky_navigation': True,
       'navigation_depth': 4,
       'includehidden': True,
       'titles_only': False,
   }
   
   html_logo = "./_static/logo.png"
   html_static_path = ['_static']
   html_js_files = [
       'my_custom.js',
   ]
   

9. my_custom.js写法（以下为示例）

   • 下面这段代码用来设置主题左上角logo的重定向的链接。

   $(document).ready(function(){
       let div_logo = document.getElementsByClassName("wy-side-nav-search")[0];
       let a_logo = div_logo.getElementsByTagName("a");
       a_logo[0].href = "https://github.com/SWHL/RapidVideOCR";
       a_logo[0].target = "_blank";
   });
   

10. 查看效果：打开build/html/index.html