美文网首页TW
Sphinx + rseStructuredText 生成 ht

Sphinx + rseStructuredText 生成 ht

作者: 零零兔 | 来源:发表于2019-05-30 16:34 被阅读2次
    Sphinx 是一种工具,它允许开发人员以纯文本格式编写文档,以便采用满足不同需求的格式轻松生成输出。这在使用 Version Control System 追踪变更时非常有用。纯文本文档对不同系统之间的协作者也非常有用。纯文本是当前可以采用的最便捷的格式之一。
    
    虽然 Sphinx 是用 Python 编写的,并且最初是为 Python 语言文档而创建,但它并不一定是以语言为中心,在某些情况下,甚至不是以程序员为中心。Sphinx 有许多用处,比如可以用它来编写整本书!
    
    可以将 Sphinx 想像成为一种文档框架:它会抽象化比较单调的部分,并提供自动函数来解决一些常见问题,比如突出显示标题索引和特殊代码(在显示代码示例时),以及突出显示适当的语法。
    

    -----引自 使用 sphinx 制作简洁而又美观的文档

    详细的安装和环境配置过程网上已经有很详细的介绍,自行搜索安装即可。

    1. 安装所有软件后,运行以下命令:

      cd: sphinx-quickstart
      
    2. 打开index.rst文件,并中添加:

      .. automodule:: run
         :members:
      

      这个是用于自动从模块读取docstring的语句,可以自动从run模块读取文档。

      如下图所示:

    Image 1.png
    1. 修改conf.py文件
      如果现在直接生成,会告诉你找不到run模块,因为Sphinx默认只会从sys.path里加载模块,所以需要将demo目录加入sys.path,所以现在打开conf.py,添加如下内容:

      import os
      import sys
      sys.path.insert(0, os.path.abspath('../..'))
      
    2. 运行Sphinx生成html文档

      sphinx-build -b html source build
      make html
      

    注意

    • make html命令要切换到source所在文件夹的根目录

      • windows下切换到上一级目录命令:cd..
      • windows下切换到上一级目录命令:cd 文件目录名
    • rst格式文件和index.rst文件要放到source目录中

      最终生成的index.html文件,即目录跳转页如下:

      Image 4.png

    参考文档:

    相关文章

      网友评论

        本文标题:Sphinx + rseStructuredText 生成 ht

        本文链接:https://www.haomeiwen.com/subject/kqsktctx.html