标签: restructuredtext

我正在记录一个包含Python组件和JavaScript组件的库.整个用户文档和Python API文档位于reStructuredText中,使用Sphinx进行处理.JavaScript API位于jsdoc中,并使用jsdoc-toolkit进行处理.主要输出格式为HTML.我是reST,Sphinx和jsdoc的新手.

我已经建立了一个构建系统,因此所有生成的html页面都被转储到一个目录树中.我现在需要在主页面(从reST生成)中插入生成的Javascript文档的链接.这需要是一个相对链接,因为文档可能位于不同安装的不同位置.reST将自动解析完整的URL,但我无法弄清楚如何使其插入相对链接.构造如:ref:和:doc:似乎没有帮助,因为他们希望目标是reST.

有任何想法吗？

如何在ReStructured Text中使用颜色？例如,**hello**翻译成<strong>hello</strong>.我怎样才能使重组(rst2html.py)翻译的东西 成<font color="####">text</font>？

我想过..raw :: html,但它引入了空白行.我想插入没有空行的HTML标签.

如何在reStructuredText中使一个单词的一部分变为粗体？

这里是什么,我需要一个例子:".rst代表- [R Ë 小号 tructured 牛逼分机."

我正在使用Sphinx编辑我的项目的文档,而Sphinx又使用reStructuredText作为标记语言.

我有一个简单的表(与网格表相对),其中最右边的列报告包含我想要正确对齐的数字,但我找不到如何实现这一点.

============  =====================
Event               Score variation
============  =====================
Event 1                        +100
Event 2                         -25
Event 3                        -400
============  =====================

如果这可以让我解决问题,我很乐意切换到网格表.

如何在reStructuredText中创建一个不间断的空间？

一个明显但有问题的解决方案是:

`word A`

但是不同的实现可能会对它进行不同的处理,例如rst2latex或rst2pdf.另外,它以斜体显示.

我发现自己有一个用例,除了从基于Sphinx的文档源生成HTML和PDF之外,我还想生成reStructuredText源文件的Markdown版本.

我的初步研究没有在Sphinx中找到任何核心或扩展支持.除了手动使用pandoc或为任务创建新的Sphinx扩展外,是否有更简单/更集成的解决方案？

我试图在子弹列表中包含reStructuredText的源代码; 像这样:

- List item 1 ::

  code sample...
  code sample...

- List item 2 ::

  code sample...
  code sample...

但是,我收到以下警告: System Message: WARNING/2 Literal block expected; none found.

列表中的空行由单个空格缩进.有任何想法吗？

因此,reStructuredText是 Python代码文档的推荐方法,如果你足够努力,你可以 在sphinx文档中找到 如何规范化你的函数签名文档.所有给出的示例都是单行的,但是如果参数描述是多行的,如下所示呢？

def f(a, b):
    """ Does something with a and b

    :param a: something simple
    :param b: well, it's not something simple, so it may require more than eighty
              chars
    """

那是什么语法/惯例？我应该缩进吗？它会破坏reSTructuredText渲染吗？

我正在使用Sphinx为我的项目生成文档.

在这个项目中,我描述了yaml文件中的可用命令列表,一旦加载,就会在表单中生成一个字典,{command-name : command-description}例如:

commands = {"copy"  : "Copy the highlighted text in the clipboard",
            "paste" : "Paste the clipboard text to cursor location",
            ...}

我想知道的是,如果sphinx中有一个方法在make html循环期间加载yaml文件,以某些reStructuredText格式(例如定义列表)翻译python字典并包含在我的html输出中.

我希望我的.rst文件看起来像:

Available commands
==================
The commands available in bla-bla-bla...

.. magic-directive-that-execute-python-code::
   :maybe python code or name of python file here:

并在内部转换为:

Available commands
==================
The commands available in bla-bla-bla...

copy
  Copy the highlighted text in the clipboard

paste …

我想使用ReStructuredText在标题和图像之间添加一个空白行(或添加更多空格):

====
John 
====

.. image:: _static/john.JPG
   :alt: John
   :height: 300px
   :width: 400px

但我不知道该怎么做？