Sphinx - 注释转html文档

----开始----

参考：https://blog.csdn.net/lixiaomei0623/article/details/120530642

现在sphinx-doc的master或者v1.4版本后就支持中文（简体+繁体）搜索了。

sphinx-doc的中文搜索是依靠jieba这个开源的类库来实现的，这个类库就支持简体和繁体的切分，所以就很容易实现了。

使用

第一，你的系统需要安装jieba类库， pip install jieba

第二，接下来修改sphinx的conf.py文件，为项目设置为中文的搜索配置。

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
html_search_language = 'zh'

第三，可选配置

# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
# html_search_options = {'dict': '/usr/lib/jieba.txt'}   # 根据需要设置jieba的词典路径

第四，接下来重新编译生成文档。make html

sphinx的基本搜索原理

在编译的时候：

1. 先对文本进行切词，把中文切分，
2. 然后制作一个大的map对象，把关键字做为key，url做为value，保存到js文件。
3. 搜索的时候寻找对应的关键字key，拿到url作为列表展示。

 

1. pip install sphinx,  pip install sphinx-rtd-theme 

2. common_utils_data文件父目录上添加一个doc文件夹，cd doc文件夹（在另一个文件夹生成html文档）

3. 修改生成的conf.py文件

import os
import sys
sys.path.insert(0, os.path.abspath('../../common_utils_data'))

4. conf.py修改扩展extensions，添加功能【包括注释中的文档】、【支持NumPy和Google风格】、【包括测试片段】、【链接到其他项目的文档】、【TODO项】、【文档覆盖率统计】、【通过javascript呈现数学】

extensions = [
'sphinx.ext.viewcode',
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
]

html_theme = ['sphinx_rtd_theme']

在外面的index.rst文件加上modules，注意modules.rst的位置如果modules.rst在source文件夹里面，需要填 source/modules.rst

 

 

 

  

5.命令行进入doc目录，执行生成API文档命令sphinx-apidoc -o source ../common_utils_data/

 然后 windows执行make html ， linux 执行make .\html

 

6. 如何编辑新的rst文件

可以自行新增rst文件，第一行文字下面加上======代表这是分割线，上面的第一行一般是标题，然后-----代表副标题的分割线

**bold**

*italic*

bullet: 前面放一个星号 + 空格即可

insert an image(如何插入图片) 在source文件路径下，新增一个image文件夹，图片放里面，然后在rst文件里写上：

.. figure:: 以新增rst路径为标准的image路径
   :alt: Jubler configuration
   :scale: 40%
   :align: center
    //写标题要空出一行，然后下面开头要用三个空格对齐上面的内容
   这里写图片标题   

新增rst部分

.. _uniquename:

标题
=============

副标题
-------------

* 编号1
* 编号2

测试插入行内图片|inlineimage|

.. _open:


副标题分割
-------------

正文内容

#插入图片,底下都要留三个空格符号对齐.. figure
.. figure:: /images/test.png
   :alt: Common_utils_data
   :align: center 

   *这个是图片标题，上面空一行*

#行内图片如何插入
.. |inlineimage| image:: /images/image.png
                 :scale: 65%

.. raw:: html
   <iframe width="560" height="315" src="https://www.youtube.com/embed/DSIuLnoKLd8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

:ref:`正文link到Open的副标题位置<open>` 

.. admonition:: 蓝色的提示框
   蓝色提示框内的内容

 

index.rstWelcome to common_utils_data's documentation! :ref:`这是链接地址<uniquename>`

=============================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

　　./source/beforeyoubegin
   ./source/modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

 

新增的rst要加入index.rst,

 

 

 

 

部署上github:

在github创建一个新的repository

git add --> adds files to staging area

git commit --> commit files

git push --> pushes files to online repo

.gitignore 忽略掉临时文件，docs/build/  docs/source/_templates/

 

 

 

----结尾----