我正在制作一个框架,让开发人员使用reStructuredText描述他们的包.我想将reStructuredText解析为HTML,以便我可以在GUI中显示它.
我熟悉优秀的Sphinx,但我从来没有解析过reStructuredText.我想象了一个函数,它接受一串reStructuredText,可能还有几个额外的参数,并返回一个HTML字符串.
所以我查看了Docutils,它负责解析reStructuredText.我根本无法理解如何找到这个功能.网上的文档很多.该docutils.parsers.rst模块中的许多功能似乎都面向文件名.我没有文件名!我只是处理字符串.
我尝试创建一个Parser和一个Document并使用该parse方法,但我只是得到一个错误的.tab_width设置错误.
有谁知道如何将reStructuredText解析为HTML？
是否可以在重组文本中查看文本？
例如,<strike>在转换为HTML时呈现为标记的内容,例如:
ReSTructuredText
我尝试在reStructuredText中插入粗体文本的链接但是失败了.
这是我的第一个来源:
**Lorem ipsum dolor sit amet, `consectetur <http://www.example.com>`_
adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua.**
但我得到了:
<strong>Lorem ipsum dolor sit amet, `consectetur <http://www.example.com>`_
adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua.</strong>
我想得到这个:
<strong>Lorem ipsum dolor sit amet, <a href="http://www.example.com">consectetur</a>
adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua.</strong>
我刚刚学习Sphinx,我需要编辑ReST文件.它有智能编辑器吗？比如,一个编辑器,它给我代码着色,简单的缩进,代码完成(希望)等.
Docutils是一个很棒的包.如果您使用Django,admindocs包需要docutils.可以使用Web浏览器安装说明,但是如果您是远程的并通过SSH登录终端怎么办？那个案子怎么安装？如果您只是想要快速配方来完成终端的工作怎么办？
我正在使用sphinx为项目生成html文档.我广泛使用字段列表.
生成html时,如果标签的长度最多为14个字符,则每个标签/值对将呈现为具有两个单元格的单个表行.
如果一对标签超过14个字符,则标签/值将呈现为两个表行.
我想将包装限制增加到更大的值(例如40).我发现限制是由--field-name-limitdocutils选项控制的.但是,我找不到如何通过sphinx设置此值.
我docutils.conf在文档根目录中创建了一个文件,其中包含以下内容:
[general]
dump_settings: 1
dump_internals: 1
[html4css1 writer]
field_name_limit: 40
运行sphinx时会读取该文件.打印设置和内部 - 由于部分中的值[general].在打印值中,field_name_limit打印有价值40.尽管如此,我描述的包装仍然出现在html输出中.
如何设置值field_name_limit以便获得所需的输出？
我正在使用rst2htmldoctils附带的工具从reST创建HTML .似乎代码已经将id属性分配给各个部分,这些部分可以用作URL中的片段标识符,即作为跳转到页面的特定部分的锚点.这些id值基于部分标题的文本.当我更改标题的措辞时,标识符也会更改,从而使旧URL无效.
有没有办法指定要用作给定部分的标识符的名称,以便我可以编辑标题而不会使链接无效？如果我从我自己的脚本中自己调用docutils发布者,会有办法吗？
在自定义Sphinx域中,我想创建对不同域中另一个节点的引用.例如:
.. py:class:: foo.bar
Lorem ipsum.
.. example:directive:: baz -> foo.bar
Sit amet, sit.
我example:directive::说我的"方法" baz返回一些类型foo.bar,这是一个Python类.所以我想将其与其他py:class:: foo.bar描述交叉引用.
from sphinx.directives import ObjectDescription
class ExampleDescription(ObjectDescription):
def handle_signature(self, sig, signode):
# lots of parsing and node creation here
# parsed_annotation = "foo.bar"
signode += addnodes.desc_returns(parsed_annotation, parsed_annotation)
在我的自定义域中,我正在解析我的指令并构建元素,这一切都很好,甚至在我的example域中交叉引用也可以通过子类化sphinx.domains.Domain:resolve_xref方法来正常工作.我只是不确定如何以编程方式在我的handle_signature方法中插入一个节点,该节点稍后被解析为另一个域中的节点.我会以某种方式实例化sphinx.domains.python.PyXRefRole吗？
HTML中的预期结果如下:
<dl>
<dt>
<code>baz</code>
?
<a href="example.html#py.class.foo.bar">
<code>foo.bar</code>
</a>
</dt>
</dl>
我想做多个版本的文档,这些版本在包含的部分中有所不同.为此,我通常使用唯一的指令或ifconfig扩展名.但是,我不能将任何与toctree指令结合使用.
我基本上想要的是这样的:
.. toctree::
:maxdepth: 2
intro
strings
datatypes
numeric
.. only:: university
complex
有没有办法做到这一点？
我在交叉引用自定义指令生成的部分时遇到问题。
这是指令：
from docutils import nodes
from docutils.parsers import rst
class TestDirective(rst.Directive):
has_content = False
required_arguments = 1
option_spec = {}
def run(self):
my_arg = self.arguments[0]
target_node = nodes.target('', '', refid=nodes.make_id(my_arg))
section = nodes.section(
'',
nodes.title(text=my_arg),
ids=[nodes.make_id(my_arg)],
names=[nodes.fully_normalize_name(my_arg)])
return [target_node, section]
def setup(app):
app.add_directive('mytest', TestDirective)
这是它的使用方法：
=============
Test document
=============
.. mytest:: section1
Section 1 content.
.. _section2:
section2
========
Section 2 content.
现在，以下仅适用于section2：
Here are links to :ref:`section1` and :ref:`section2`.
该链接仅正确生成section2，我收到以下错误：
test.rst:19: WARNING: undefined label: …