标签: python-sphinx

我目前正在将sphinx生成的文档集成到我的Django应用程序中。我希望文档扩展我的应用程序模板。Sphinx生成的HTML应该如下所示

{% extends "base.html" %}
{% block content %}
...

我的狮身人面像主题模板看起来是：

{{ '{% extends "base.html" %}' }}
{{ '{% block content %}' }}
...

有更好的方法来实现这一目标吗？

我正在寻找一个Javascript API文档框架,其功能类似于JSDoc,但会在代码注释中使用易于重构的文本或markdown(而不是html)

奖金:将与Sphinx很好地融合.但是,我不想维护单独的文档,而是从注释生成API文档.

http://code.google.com/p/jsdoc-toolkit/

如何在sphinx中定义应使用的.rst文件和目录？

我想在测试/构建/文档脚本中包含一个自动文档生成器。 在我的工作空间中执行了sphinx-quickstart，并创建了一个index.rst文件。当sphinx使用重组的文本文件作为文档时，我在工作区中导航并使用sphinx-autogen手动创建它们。结果进入了task.rst文件（见下文）。

当我使用“ make html”时，我会收到一些警告：

警告：自动模块的无效签名（u'tasks / add_to_config'）

警告：autodoc无法导入/查找模块'tasks.add_to_config'，它报告错误：“没有名为wl_build.tasks的模块”，请检查您的拼写和sys.path

警告：不知道要导入哪个模块以自动记录u'tasks / add_to_config'（尝试在文档中放置“ module”或“ currentmodule”指令，或给出明确的模块名称）

...

我的index.rst

Welcome to build's documentation!
====================================

Contents:

.. toctree::
   :maxdepth: 2

.. automodule:: tasks/add_to_config
   :members:

.. automodule:: tasks/build_egg
   :members:   

任务

tasks Package
=============

:mod:`tasks` Package
--------------------

.. automodule:: tasks.__init__
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`add_to_config` Module
---------------------------

.. automodule:: tasks.add_to_config
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`build_egg` Module
-----------------------

.. automodule:: tasks.build_egg
    :members:
    :undoc-members:
    :show-inheritance:

假设我有一堂课

class A(object):
  def myfunction():
    """A."""
    pass

和一个子类

class B(A):
  def myfunction():
    pass

是否可以使用sphinx从A.myfunction继承B.myfunction的API文档？B.myfunction的文档应为"A".同样.

如何在Sphinx中定义多个全局替换？

我在这个问题中看到如何使用conf.py中的rst_prolog创建全局替换.例如,

rst_prolog = '.. |my_conf_val| replace:: 42'

我能找到的所有这些例子只能在rst_prolog中定义一个替换,但我想做多个.我试过这个:

rst_prolog = """.. |sub1| replace:: mine1\
         .. |sub2| replace:: mine2"""

当我把| sub1 | 到第一个文件中的文本,| sub1 | 是(毫不奇怪)替换为:

mine1 .. |sub2| replace:: mine2

这里的语法是什么？

当我查看文档时,大多数页面底部都有前一章和下一章链接/按钮,例如virtualenv.我无法使用Sphinx文档工具找到如何为我的项目文档完成此操作.有人能告诉我这是如何工作的或指向一个有用的资源(虽然我已经搜索了很多)？

我是Sphinx和reStructuredText的新手。

在我的狮身人面像中，conf.py我定义了：

version = '0.0.2'

里面的tutorial.rst我想要访问的version变量，并显示0.0.2在我的HTML文件。我试过了：

version

|version|

:version:

.. |version|

.. :version:

我成功测试了该版本的内容。

.. ifconfig:: version == '0.0.2'

    This prints!

这令人鼓舞，但不是我想要的。

我正在使用Sphinx记录Python项目。

该.. csv-table::指令似乎有点不一致。

主要问题是单元格中的新行。还有我可疑的心理健康。

如下代码：

.. csv-table::
    :header: Header1, Header2, Header3

    A, B, "These lines appear as one line, 
    even though they are written in two lines."
    C, D, "| These lines appear as two lines, 
    | but they are indented, and my OCD will simply not allow it."
    E, F, "| If I continue this line in another line,
    it will appear in a new line."
    G, H, "If there is a blank line between the two …

我使用了出色的Sphinx工具来创建一些文档，并且试图通过将同一部分的章节分成单独的文件来使代码库保持模块化形式。（有关“章节”和“部分”的定义，请参见此处。）

我尝试使用两个文件来执行此操作test1.rst：

######
Part 1
######

*********
Chapter 1
*********

Section 1
=========
Test Content 1.

和test2.rst：

*********
Chapter 2
*********

Section 2
=========
Test Content 2.

它们index.rst像这样包含在其中：

.. toctree::
   :maxdepth: 2

   test1
   test2

但是，在构建时，第2章没有嵌套在第1部分中。这是为什么？是否有任何方法无需创建脚本即可将它们附加到单个文件中，就像下面的示例一样？

例：

######
Part 1
######

*********
Chapter 1
*********

Section 1
=========
Test Content 1.

*********
Chapter 2
*********

Section 2
=========
Test Content 2.

例如：

def foo():
    '''
    .. highlight:: python
    import sys
    '''

不产生所需的输出（它逐字打印单词“ highlight”，并且不以任何特殊方式格式化以下代码）。也会发生同样的情况code-block。

我尝试了不同的缩进等。无论如何，生成器以大致相同的方式成功，但未获得所需的输出。