开发者

Sphinx环境配置及VScode编写Rst文档转html的步骤

目录
  • Sphinx环境配置
  •  python安装步骤
  • Sphinx安装步骤
  •  Rst语法格式
    •  标题格式
    • 超链接格式 
    •  图片格式
    • 代码格式
  •  总结

    Sphinx环境配置

    • 安装python3
    • 通过py编程客栈thon3安装sphinx

    sphinx官方网站:Installing Sphinx — Sphinx documentation​​​​​​

    python官方网站:Welcome to Python.org

    sphinx主要用于编写 reStructuredText 和 Markdown 格式技术文档,

    编写此类技术文档时Sphinx工具可将其转为htmlphp、pdf、ePub等格式;更有者托管到github中并导入readthedocs网站。 

     python安装步骤

    进入python官网

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    下载安装包

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    打开exe文件 ,勾选配置到系统环境变量并选择自定义安装

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    保持默认Next

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    这里初学者默认安装路径,方便后面用命令安装sphinx

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    安装完成界面

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    win+R打开命令窗输入python,确定是否安装成功和安装版本是否为python3

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    Sphinx安装步骤

     Windows命令窗输入以下命令,安装Sphinx软件包

    国内最好用华清源安装,使用-i指定安装源

    py -3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx

    安装中可能会出现pip版本过低安装不了Sphinx,需运行命令更新pip再安装Spinx

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     Sphinx安装中

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    安装完成,在Windows命令框顺序输入每一行命令创建\demo\test文件夹试运行

    mekdir demo //创建demo文件夹
    cd demo     //打开demo文件夹
    mekdir test //创建test子文件夹
    cd test     //打开test子文件夹

    Windows命令框输入以下命令打开Sphinx工具配置基本参数

    sphinx-quickstart

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     这些配置参数都可以在之后的conf.py文件中打开重新更改

    配置完成后在Windows目录下可以看到生成的基本项目框架文档

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    build:存放最终生成的文档如html、pdf、ePub 

    source:存放Rst格式等文件以及图片数据

    Makefile:批处理指令,使用make命令时用来构建文档输出

     配置完后在source文件中会出现 index.rst 和 conf.py 两个文件;用户可根据需求编写这两个文档达到自己的效果

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    conf.py : 一个pythom文件,用于存放Sphinx的配置参数

    index.rst :文档项目的root目录。多个文件时可用于连接其余文件。 

    编写 conf.py 和 index.rst 文件

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    Introduction
    ============
    This is the introduction of documentation
     
    API
    ===
    :doc:'Run API</demo_test>'

    :doc:命令属于寻找目标文件运行 

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    import os
    import sys
    sys.path.insert(0,os.path.abspath('http://www.devze.com../..'))

     运行命令 sphinx-build -b html source build 和 make html 生成 .html文件

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     最终在build文件夹中生成.html文件,并可通过网页查看

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     上图是相当于是通过 Rst 转换 html 的默认框图,内容排版都可自定义

    VScode编写Rst格式文件  VScode环境配置 下载插件 reStructuredtext 和 RST Preview(可以实时显示效果变化)

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     source文件夹中创建 .rst 格式文件使用VScode打开

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    安装完插件后用户可以打开图上这个窗口,进行实时显示当前Rst格式的排版  

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     Rst语法格式

    其中空格要谨慎使用,其中空格运用得当能产生不一样的效果反之则不符合语法标准报错

     标题格式

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     对应显示效果分别是一级标题、二级标题、三级标题、四级标题、五级标题

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    超链接格式 

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     超链接目前使用的有以下两种方式:Sphinx官网是先声明后引用、Python官网是直接引用

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     图片格式

    Sphinx环境配置及VScode编写Rst文档转html的步骤

      图片目前开发者_C开发使用有以下两种方式:bd_logo1.png是引用网址、logo.png是引用当前文件的相对路径

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     表格格式

    //表格类型一
     
    ==== ====== ========== ==== == ===
    编号 名称   NAND FLASH eMMC SD USB
    ==== ====== ========== ==== == ===
    1    MODE0  0          0    0  1
    2    MODE1  1          1    1  0
    3    CFG1-4 1          0    0  X
    4    CFG1-5 0          1    0  X
    5    CFG1-6 0          1    1  X
    6    CFG1-7 1          0    0  X
    7    CFG2-3 0          1    0  X
    8    CFG2-5 0          0    1  X
    ==== ====== ========== ==== == ===
     
    //表格类型二
     
    +------------+------------+-----------+ 
    | Header 1   | Header 2   | Header 3  | 
    +============+============+===========+ 
    | body row 1 | column 2   | column 3  | 
    +------------+------------+-----------+ 
    | body row 2 | Cells may span columns.| 
    +------------+------------+-----------+ 
    | body row 3 | Cells may  | - Cells   | 
    +------------+ span rows. | - contain | 
    | body row 4 |            | - blocks. | 
    +------------+------------+-----------+
     
    //表格类型三
     
    .. csv-table:: Frozen Delights!
      :header: "Treat"python, "Quantity", "Description"
      :widths: 15, 10, 30
     
     
      "AlBATross", 2.99, "On a stick!"
      "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
      crunchy, now would it?"
      "Gannet Ripple", 1.99, "On a stick!javascript"
    

      表格目前使用有以下三种方式:

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     标注以及特殊提示符

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     以下是显示效果

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    代码格式

    需要代码每行进行缩进一个空格

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     显示效果

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    RST格式文件编写完成后需要重新进入Windows命令窗\demo\test文件下

    输入 sphinx-build -b html source build 和 make html 命令生成新的 .html 文件

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     以下是网页中显示效果

    Sphinx环境配置及VScode编写Rst文档转html的步骤

    Sphinx环境配置及VScode编写Rst文档转html的步骤

     总结

    由此本文分享结束

    Rst格式还有很多地方需要探究,Spinx工具亦是如此

    到此这篇关于Sphinx环境配置及VScode编写Rst文档转html的文章就介绍到这了,更多相关Sphinx环境配置内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

    0

    上一篇:

    下一篇:

    精彩评论

    暂无评论...
    验证码 换一张
    取 消

    最新开发

    开发排行榜