标签: restructuredtext

我有第一个文件包含像

.. figure:: examples/foo.png 
    :scale: 80%

    Fig. 1 : Illustration of the awesomeness of stackoverflow

现在我希望将此文件转换为markdown.我试过用pandoc,

pandoc -s -w rst --toc foo.rst -o foo.md

但输出文件foo.md似乎忽略了图形包含线.那么,如何在不失去数字真棒的情况下转换为markdown文件呢？谢谢

我在构建我的Sphinx用户指南时遇到了问题.我想通过一个包含章节标题和概述的主登陆页面(index.rst)来形成章节,然后分开包含在不同文件中的子章节(part1.rst,part2.rst).我正在尝试使用"toctree"来插入单独的子部分,但是我遇到了一个嵌套问题,我的toctree被吸入了我的概述部分.(注意:我没有使用该..include::指令,因为我希望不同网页上显示的子节顺序链接.我也希望结构正确,以便它们在UG的pdf渲染版本中很好地布局).

index.rst

Chapter 3                                                
===============================                                                 

Overview                                                                        
--------                                                                        

Yadda yadda yadda.

.. toctree::                                                                    
   :hidden:                                                                     

   part1                                                                        
   part2

Run Code Online (Sandbox Code Playgroud)

part1.rst

Part 1
------

This part is all about yadda.

Run Code Online (Sandbox Code Playgroud)

part2.rst

Part 2
------

More yadda.

Run Code Online (Sandbox Code Playgroud)

我希望得到的结构是:

Chapter 3
  - overview
  - part 1
  - part 2

Run Code Online (Sandbox Code Playgroud)

但我得到的是

Chapter 3
  - overview
    - part 1
    - part 2

Run Code Online (Sandbox Code Playgroud)

我在文件底部包含的toctree似乎属于"概述"部分,而不是在主章节上下文中运行.我尝试在文件的顶部插入toctree,但后来我得到了这个顺序:

Chapter 3
  - part 1
  - part 2
  - overview

Run Code Online (Sandbox Code Playgroud)

似乎必须有一种方法可以正确地做到这一点,但我无法在Sphinx网站或SO上找到任何东西.任何帮助表示赞赏.

使用autodoc和类似的工具允许从源文档字符串编译文档.但是,它似乎不允许函数或类docstrings中的任意ReST节标题,并产生错误:

SEVERE: Unexpected section title.

我在尝试记录numpy样式指南时遇到了类似的问题numpydoc:没有sphinx的意外部分标题是问题, numpy如何将docstrings处理成sphinx文档中的参数

然而,在这里,我实际上是在记录JavaScript,并且只想在文档字符串中使用任意的节标题和ReST.

Javascript docstring api:sphinx jsapidoc

我想用我自己的自定义样式扩展Sphinx和ReadTheDocs使用的主题.

我能做到这一点的最佳方式是什么,以便我的改变能够坚持下去？

在Sphinx,我知道你可以做到:

.. raw:: html

    <div style="margin-top:10px;">
      <iframe width="560" height="315" src="http://www.youtube.com/embed/_EjisXtMy_Y" frameborder="0" allowfullscreen></iframe>
    </div>

在pypi,有没有办法做到这一点？

youtube视频怎么样？

有先前的问题,解释如何将色彩范围增加了一些新结构化.

回顾一下这个程序:

首先,你有这个角色.

.. role:: red

An example of using :red:`interpreted text`

它转化为如下.

<p>An example of using <span class="red">interpreted text</span></p>

现在,你有了红色类,你可以使用CSS来改变颜色.

.red {
    color:red;
}

如果您想要跨越多行的文本,您如何做到这一点？例如:

.. role:: red

:red:`paragraph 1

      paragraph 2

      paragraph 3`

第1,2和3段都是"红色".如果我尝试这样做,我会收到警告消息:

警告:内联解释的文本或短语引用start-string,不带结束字符串.

它不会创建跨度并在文本中插入":red:".它只是不将其解释为字符串(如警告所示).

基本上,这可以在reStructuredText中完成,如果可以,怎么做？

我正在使用Sphinx 1.1.3.

我使用latexpdf和sphinx生成从rst到pdf的文档.

如何在PDF中添加一些分页符(=新页面)？

现在我使用PageBreak,但它只适用于rst2pdf.

.. raw:: pdf

   PageBreak

我在使用Sphinx-doc的Ref函数时遇到问题,我在一个段落上面放了一个标签然后我尝试从另一个doc链接到那个标签,但是在同一个项目中.

我在一个文档中使用的标签:

.. _hal_1k_1p:

而我尝试使用链接到该标签:

:ref:`Link title hal_1k_1p`

但是我在构建doc时只收到此错误消息:

警告:未定义标签:链接标题hal_1k_1p(如果链接没有标题,则标签必须位于节标题之前)

我究竟做错了什么？

我知道如何使用自定义文本创建外部超链接.

`My cool link <http://www.asdf.com>`_

但我想链接到内部参考.

.. _foo:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

所以我想做点什么

`My cool internal link <foo>`_

但这不起作用.

我正在尝试调整 wiki 页面中的图像大小，但没有任何效果：图像始终以 100% 的页面宽度呈现。

我尝试使用 reStructuredText：

.. image:: image.jpeg
   :height: 100px
   :width: 200px
   :scale: 50 %
   :alt: alternate text

（和不同的组合，忽略一些行）。

然后我也试过了

![](image.jpeg =250x)

但是，同样，它不会改变所呈现图像的大小。

任何的想法？