restructuredtext | 易学教程

Sphinx和rst在科研笔记和学术博客中的高效用法

阅读更多关于 Sphinx和rst在科研笔记和学术博客中的高效用法

什么是RST？ reStructuredText 是扩展名为 .rst 的纯文本文件，含义为"重新构建的文本"，也被简称为：RST 或 reST；是 Python 编程语言的 Docutils 项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。该项目类似于 Java 的 JavaDoc 或 Perl 的 POD 项目。 Docutils 能够从 Python 程序中提取注释和信息，格式化成程序文档。 .rst 文件类似于.md(Markdown)文件，是轻量级标记语言的一种，被设计为容易阅读和编写的纯文本，并且可以借助 Docutils 这样的程序进行文档处理，可以方便地转换为 HTML , Latex, Markdown 等多种格式。 rst在标记功能上比md丰富太多了，而且在Sphinx的框架下可以非常方便地使用各种插件，来实现各种不同特定需求。比如地学领域最常用的绘图和数据处理软件gmt，其开发团队现在已经开发了适用于Sphinx的插件 sphinx_gmt ，这个插件的功能就是可以直接在rst文件中进行绘图，类似于Sphinx内置的python绘图插件 .. plot:: 。比如在rst文件中写入如下所示的文字，就可以直接自动根据你的gmt绘图命令将图片绘制好并嵌入到最终生成的html文件

Python 的 RST 文件是什么

阅读更多关于 Python 的 RST 文件是什么

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 源代码的程序员很容易读它。 reST 解析器的引用实现是 Python 编程语言中的 Docutils 文本处理框架的一个组件，但是还可以使用其他解析器。没有正式的 mime 类型注册为 reStructuredText，但非官方的是 text/x-rst 可以将 RST 文件理解为 Python 使用的 Markup 文件就可以了。官方的使用手册，请参考链接： https://docutils.sourceforge.io/docs/user/rst/quickstart

1.浅谈标记语言markdown

阅读更多关于 1.浅谈标记语言markdown

Markdown简介 Markdown是一种轻量级标记语言，创始人为约翰·格鲁伯(英语：John Gruber)。它允许人们使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML（或者HTML）文档。这种语言吸收了很多在电子邮件中已有的纯文本标记的特性。由于Markdown的轻量化、易读易写特性，并且对于图片，图表、数学式都有支持，目前许多网站都广泛使用Markdown来撰写帮助文档或是用于论坛上发表消息。如GitHub、Reddit、Diaspora、Stack Exchange、OpenStreetMap 、SourceForge、简书等，甚至还能被使用来撰写电子书。历史 John Gruber在2004年创造了Markdown语言，在语法上有很大一部分是跟亚伦·斯沃茨（Aaron Swartz）共同合作的。这个语言的目的是希望大家使用“易于阅读、易于撰写的纯文字格式，并选择性的转换成有效的XHTML（或是HTML）”。其中最重要的设计是可读性，也就是说这个语言应该要能直接在字面上的被阅读，而不用被一些格式化指令标记（像是RTF与HTML）。因此，它是现行电子邮件标记格式的惯例，虽然它也借鉴了很多早期的标记语言，如：Setext、Texile、reStructuredText。Gruber也编写了Perl脚本：Markdown.pl

create a role (font color) in sphinx that works with `make latexpdf`

阅读更多关于 create a role (font color) in sphinx that works with `make latexpdf`

问题 I'm used to write Rest documents while I never used LaTex. What I would like to do is create some font color roles that I can add inline the text (e.g. :red: this text is red ) that work both in html and in latexpdf compilation. I've found a similar question here, but I cannot reproduce it. I think that the magic will be done changing the conf.py file, but I didn't find out how. Moreover, during the latexpdf compilation, in the _build/latex directory, there is a sphinx.sty file that contains

Numbered :math: equations in reStructuredText

阅读更多关于 Numbered :math: equations in reStructuredText

问题 How can I make an equation in restructured text, that is followed by an equation number: p = f(x) (1) .. math:: p = f(x) would only lead to: p = f(x) 回答1: .. math:: p=f(x) :label: eq:pfx 回答2: Looking at this a few years later, it appears that the number is still not automatically placed on the right of the equations. I'd therefore like to supplement the accepted answer a bit. First you add a label to the equation in the rst file: .. math:: :label: pfx p = f(x) This will generate a <span> of

WARNING: document isn't included in any toctree for included file

阅读更多关于 WARNING: document isn't included in any toctree for included file

问题 I'm getting the warning: WARNING: document isn't included in any toctree for files that exist in the document because they've been explicitly included. So I have the index file: .. toctree:: :maxdepth: 2 pages/0010-foo pages/0020-bar In the file 0020-bar.rst, I'm specifically including a number of other files, as in: .. contents:: :local: .. include:: /pages/reference-architecture/technical-considerations/0070-baz.rst But when I build the project, I still get a warning that 0070-baz.rst isn't

How to make PyPi description Markdown work?

阅读更多关于 How to make PyPi description Markdown work?

问题 I uploaded a package to PyPi using: python setup.py register -r pypi python setup.py sdist upload -r pypi I'm trying to modify the description, I wrote ( please don't edit the formatting of the following piece of code, I made it on purpose to demonstrate my problem ): **my plugin** This plugin enables you to ... For example: ```python @attr(section='MySection', id=1) def test_function(self): """ Bla bla bla """ pass ``` However, the text appears as it is, without the markdown formatting. What

Human readable iterables in Sphinx documentation

阅读更多关于 Human readable iterables in Sphinx documentation

问题 Sphinx-autodoc flattens dicts, lists, and tuples - making long ones barely readable. Pretty-print format isn't always desired either, as some nested containers are better kept flattened than columned. Is there a way to display iterables as typed in source code? 回答1: Get it straight from source, and add an .rst command for it: # conf.py from importlib import import_module from docutils import nodes from sphinx import addnodes from inspect import getsource from docutils.parsers.rst import

Human readable iterables in Sphinx documentation

阅读更多关于 Human readable iterables in Sphinx documentation

sphinx 编写文档使用记录

阅读更多关于 sphinx 编写文档使用记录

目录 1、安装 sphinx 环境 2、生成 Sphinx 工程配置主题和插件 3、编写并构建文档 1、安装 sphinx 环境首先安装 python 环境这里可以安装 anacond ，使用起来比较方便。参考： Anaconda的安装和详细介绍（带图文）我这里直接使用 scoop 来安装。 # 安装 miniconda scoop install -g miniconda3 Installing 'miniconda3' (4.7.12.1) [64bit] Miniconda3-4.7.12.1-Windows-x86_64.exe (51.5 MB) [============================================================] 100% Checking hash of Miniconda3-4.7.12.1-Windows-x86_64.exe ... ok. Running installer... done. Linking C:\scoop\apps\miniconda3\current => C:\scoop\apps\miniconda3\4.7.12.1 Creating shim for 'python'. Creating shim for 'pythonw'. Creating shim for

订阅 restructuredtext