标签: python-sphinx

我讨厌RST,但喜欢狮身人面像.有没有办法让sphinx读取markdown而不是reStructuredText？

我正在尝试使用Sphinx来记录Python中的5000多行项目.它有大约7个基本模块.据我所知,为了使用autodoc我需要为我的项目中的每个文件编写这样的代码:

.. automodule:: mods.set.tests
    :members:
    :show-inheritance:

这太繁琐了,因为我有很多文件.如果我能指定我想要记录'mods'包,那将会容易得多.然后,Sphinx可以递归地遍历包并为每个子模块创建一个页面.

有这样的功能吗？如果没有,我可以写一个脚本来制作所有的.rst文件,但这会花费很多时间.

如何将reST/Sphinx页面中的交叉引用插入同一文档集中另一页的子标题或锚点？

默认情况下,Sphinx不会为__init __(self)生成文档.我尝试过以下方法:

.. automodule:: mymodule
    :members:

和

..autoclass:: MyClass
    :members:

在conf.py中,设置以下内容只会将__init __(self)docstring附加到类docstring(Sphinx autodoc文档似乎同意这是预期的行为,但没有提到我正在尝试解决的问题):

autoclass_content = 'both'

我喜欢doxygen来创建C或PHP代码的文档.我有一个即将推出的Python项目,我想我记得Python没有/* .. */评论,并且还有自己的自我文档工具,这似乎是pythonic的文档方式.

由于我熟悉doxygen,我如何使用它来生成我的Python文档？有什么特别需要注意的吗？

我正试图开始使用Sphinx并且似乎有无情的问题.

命令: docs/sphinx-quickstart

我回答所有问题,一切正常.

命令: docs/ls

一切看起来都很正常.结果:build Makefile source

命令: sphinx-build -d build/doctrees source build/html

它似乎工作.我能够打开index.html文件,看到我想要的"shell".

当我尝试将我的实际源代码作为source文件夹时遇到问题.

命令: sphinx-build -d build/doctrees ../ys_utils build/html

结果:

Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
No builder selected, using default: html
loading intersphinx inventory from http://docs.python.org/objects.inv...
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
Traceback (most recent call last):                                                                                               
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in …

我正在使用sphinx和autodoc插件为我的Python模块生成API文档.虽然我可以看到如何很好地记录特定参数,但我找不到如何记录**kwargs参数的示例.

有没有人有一个明确的方法来记录这些？

我正在使用Sphinx来记录非Python项目.我想./doc在每个子模块中分发文件夹,其中包含submodule_name.rst用于记录该模块的文件.然后我想将这些文件吸入主层次结构中,为整个设计创建一个规范.

即:

Project
  docs
    spec
      project_spec.rst
      conf.py
  modules
    module1
      docs
        module1.rst
      src
    module2
      docs
        module2.rst
      src

我试图将文件包含在主project_spec.rst文档toctree中,如下所示:

.. toctree::
   :numbered:
   :maxdepth: 2

   Module 1 <../../modules/module1/docs/module1>

但是,此错误消息导致:

警告:toctree包含对不存在的文档u'modules/module1/docs/module1'的引用

是不是可以以../某种方式在文档路径中使用？

更新:添加conf.py位置

我正在尝试使用以下代码创建一个正确嵌套的列表(遵循Sphinx和docutils文档):

1. X

  a. U
  b. V
  c. W

2. Y
3. Z

我希望这会导致两个OLs,但我得到以下输出:

<ol class="arabic simple"> 
  <li>X</li> 
</ol> 

<blockquote> 
  <div>
    <ol class="loweralpha simple"> 
      <li>U</li> 
      <li>V</li> 
      <li>W</li> 
    </ol> 
  </div>
</blockquote> 

<ol class="arabic simple" start="2"> 
  <li>Y</li> 
  <li>Z</li> 
</ol> 

我究竟做错了什么？是否无法获得以下结果？

<ol class="arabic simple"> 
  <li>X
    <ol class="loweralpha simple"> 
      <li>U</li> 
      <li>V</li> 
      <li>W</li> 
    </ol> 
  </li>
  <li>Y</li> 
  <li>Z</li> 
</ol> 

如何在reStructuredText中的表示链接中格式化文本？

具体来说,我希望从我的第一个生成以下HTML:

<a href="http://docs.python.org/library/optparse.html"><tt>optparse.OptionParser</tt> documentation documentation</a>

结果应如下所示:

optparse.OptionParser 文件

其中"optparse.OptionParser"部分是固定宽度字体.

我试过了

```optparse.OptionParser`` <http://docs.python.org/library/optparse.html>`_

然而,这给了

<tt class="docutils literal">`optparse.OptionParser</tt> documentation &lt;<a class="reference external" href="http://docs.python.org/library/optparse.html">http://docs.python.org/library/optparse.html</a>&gt;`_

看起来像这样

``optparse.OptionParser documentation <http://docs.python.org/library/optparse.html>\_