推荐一种sphinx+reStructuredText的编辑方式

摘自：https://zhuanlan.zhihu.com/p/97214287

 

推荐一种sphinx+reStructuredText的编辑方式

timger™

CRUD 程序员

Sphinx 是一种文档工具,基于reStructuredText/rst格式编写文档,

有着众多的插件和良好的生态,可以生成高质量的出版级别的文档.

具体可以参考,

译者前言 - Sphinx 使用手册​

zh-sphinx-doc.readthedocs.io

 

Sphinx在Python圈非常出名,几乎所有开源项目的文档都是sphinx编写

大部分托管在

Home | Read the Docs​readthedocs.org

 

但是一直没找到好的编写工具或者Sphinx编辑软件.

vim之类的插件容易实现,但是需要定制的很多,

有界面的sphinx-doc编写app质量都很差.

大多年久失修.或者功能缺失,比如基于pandoc的转换,需要脑补下才可以.

常用IDE, idea和pycharm里面的的插件也非常不好用.

找了很多地方

 

reStructuredText tool support​stackoverflow.com

stackoverflow和github都找遍了,这里的基本上能找到的关于sphinx-doc reStructuredText 方式的编辑软件试过了,没有一个能打的 .

无意间在github的topic下找到一个vs插件,试了一下很好用.

推荐:

 

reStructuredText - Visual Studio Marketplace​marketplace.visualstudio.com

reStructuredText tool support

reStructuredText - Visual Studio Marketplace​marketplace.visualstudio.com

如果遇到python问题

用这个指定python解释器

必须为python3以上把.python2的中文编码坑的比较

这里列举了不少的文档

reStructuredText tool support​stackoverflow.com

vs插件的特点是:

1. 完成兼容sphinx,可以渲染出html样式
2. 实时编辑实时预览

不足:

1. 不支持图片剪切

vs下载地址参见:

 

https://code.visualstudio.com/Download​code.visualstudio.com

 

如果你想支持在vs中copy图片,生成路径

可以看下Paste Image 这个插件

https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image​marketplace.visualstudio.com

 

rst相关语法的中文版本可以参见

 

reStructuredText 简介​zh-sphinx-doc.readthedocs.io

 

最后再配合 vscode 的配置 .setting.json 配置 很方便将4个缩进切到三个缩进

{
    "python.pythonPath": "./venv/bin/python3.7",
    "restructuredtext.confPath": "${workspaceFolder}",
    "editor.detectIndentation": false,
    "editor.insertSpaces": true,
    "editor.tabSize": 3,
}

 

编辑于 2019-12-18