目录

• • • • 引言
      • 使用步骤

引言

• 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 LRa --> 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