当前位置:优学网  >  在线题库

rst 格式的文档如何优雅的阅读?

发表时间:2022-06-16 13:11:16 阅读:13.1k

clone 的 nameko 的源代码后,发现 doc 下面有很多 rst 后缀的文件:

看起来像 markdown 又不是 markdown

rst 是啥,为什么不用 markdown 来写呢?

rst 用什么工具可以优雅的看?

找了网上的教程,说要把 rst 转成 html 再来看,这不是脱裤子放屁吗?

🎖️ 优质答案
  • reStructuredText。

    绝大部分 Markdown 阅读器也是先转换成 HTML 的啊……毕竟浏览器是个天然支持富文本的渲染器啊,纯自己实现那得多麻烦?无非是 Markdown 有很多 GUI 程序、内部已经封装好转换程序了,你选择文件后程序自动帮你做了转换了;现在到 reStructuredText 需要你执行个命令行做下转换而已……

    你要确实就想要个 GUI 程序直接打开就能读的,也是有的。比如 TextMate、sphinx-gui 等等;在线版的有 GroupDocs 之类的。

    而且你这时间顺序搞反了,reStructuredText 比 Markdown 还早了两年诞生呢,一直以来都是 Python 的“御用”文档格式。

    你要说 reStructuredText 不如 Markdown 流行,那确实。不过 reStructuredText 还是有一些知名项目在使用的,比如 OpenCV、LLVM、Read the Docs 等等;另外 GitHub/GitLab 等开源网站也支持直接展示 rst 文件(比如其实你可以在项目里写 README.rst、而不是 README.md)。

    OpenCV 文档 reStructuredText 源文件(那个 Sphinx 的就是)
    LLVM 文档 reStructuredText 源文件

    P.S.1 其实 Markdown 的流行也就是近几年的事情,还是因为很多笔记和邮件类软件做了支持而“出圈”的 —— Markdown 2004 年就被发明出来了,可别说 2004 年了,2014 年的时候也没多流行,那时候你听说过吗?连 GitHub 都是到了 2017 年才开始支持 Markdown。而 reStructuredText 就始终仅限于程序员之间了。在这之前很长的一段时间里 Markdown 跟 reStructuredText 在流行度上其实是难分伯仲的。

    P.S.2 其实轻量级的文本标记语言远不止这两种,比较流行的还有 Org-Mode、AsciiDoc 等等。

  • reStructuredText(RST、ReST或reST)是一种用于文本数据的文件格式,主要用于 Python 编程语言社区的技术文档。

    它是Python Doc-SIG(Documentation Special Interest Group)的 Docutils 项目的一部分,旨在为 Python 创建一组类似于 Java 的 Javadoc 或 Perl 的 Plain Old Documentation(pod)的工具。Docutils 可以从 Python 程序中提取注释和信息,并将它们格式化为各种形式的程序文档。

    从这个意义上说,reStructuredText 是一种轻量级标记语言,其设计目的是:
    (a)文档处理软件(如Docutils)可以处理它;
    (b)读和写 Python 源代码的程序员很容易读它。

    类似于markdown,不用工具也能看懂,想要好看的话,可以去搜一下restructuredtext viewer,有不少这样的工具。


    已参与了 SegmentFault 思否社区 10 周年「问答」打卡 ,欢迎正在阅读的你也加入。

  • 相关问题