标签: python-sphinx

Sphinx是Python的新文档工具.它看起来非常好.我想知道的是:

• 这对于记录C++项目有多适合？
• 是否有任何工具可以将现有文档(例如doxygen)转换为Sphinx格式？
• 是否有使用Sphinx的C++项目的在线/可下载示例？
• 任何使用过Sphinx的人提示？

我正在尝试使用Sphinx为大型python代码库自动创建api文档.

我尝试过使用build_modules.py和sphinx-apidoc.使用其中任何一个,我都可以在输出目录中成功创建包和顶级模块的第一个文档.

但是,当我构建使用时

make html

它提供了数千种此类错误:

<autosummary>:None: WARNING: toctree contains reference to nonexisting document 'rstDocs/src.Example1.class1.method1'

对于代码库中的每个类和方法.通过一些实验,我想我已经发现autosummary/autoclass指令正在创建toctrees,期望每个类和方法都有第一个文件.

除了警告之外,文档似乎运行良好,但我想摆脱它们,我想我可能错误配置了一些东西.

我也尝试过nipype/tools达到同样的效果.

我修改了apigen.py和build_modref_templates.py,为每个"缺失"文档创建了第一个存根,并使用autoclass/autofunction/automethods.但是,构建需要相当长的时间(10分钟),并且最终由于上一个构建步骤中的内存错误而崩溃.

以下是创建所有警告的示例模块rst文件:

src Package
===========

:mod:`src` Package
------------------

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

:mod:`Example1` Module
------------------------------------

.. automodule:: src.Example1
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`Example2` Module
------------------

.. automodule:: src.Example2
    :members:
    :undoc-members:
    :show-inheritance:

感谢您提供有关如何解决这些问题的建议!我想远离任何涉及修改sphinx site-package文件的解决方案.

我需要使用Sphinx记录我的Python项目.但我不能用autodoc.

当我配置我的项目时,我选择"扩展autodoc"选项,但现在如果我使用

.. autoclass:: Class

我收到一个错误:

ERROR: Unknown directive type "autoclass"

我配置了PYTHONPATH,现在它很好.但我已经有了这个问题.

我的索引文件是:

.. ATOM documentation master file, created by
   sphinx-quickstart on Thu Nov 22 15:24:42 2012.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to ATOM's documentation!
================================

Contents:

.. toctree::
   :maxdepth: 2

.. automodule:: atom

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

我需要有人告诉我如何解决问题.

谢谢

我想使用virtualenv而不是我的机器上的本机环境来构建html文档.

我已经进入了virtualenv,但是当我运行时,make html我得到错误,说模块无法导入 - 我知道错误是由于模块在我的本机环境中不可用.如何在搜索文档时指定应该使用哪个环境(例如virtualenv)？

我正在使用ReStructuredText(ReST)格式编写一些文档,以便稍后使用Sphinx生成Web页面,我找不到编写一些"粗体斜体"文本的方法.

所谓的"强调"(斜体)和"强调"(粗体)文本都有标记.他们*italic text*和**bold text**分别.我还阅读了一些关于这种格式的文档,这些格式标记不能简单地"嵌套".即***text***(或** *text* **)不产生粗体斜体文本.

仍然可能有某种方式来生成一个用粗体和斜体标记强调的文本,因为通过这种方式标记文本片段是一种普遍的做法.

我正在使用Sphinx autodoc功能根据我的Python库的文档字符串生成文档.

交叉引用的语法可在此处找到

标签必须位于该部分之前,以便允许从文档的其他区域引用该部分.

我所拥有的是我的一个类的.rst(ReStructeredText)文件.它用

.. autoclass:: classname
    :members:

为类生成文档.

我的问题是,如何从文档中的另一个.rst文档引用该类的自动生成方法？如果我尝试在方法的文档字符串中放置一个标签,Sphinx会抱怨.如果我尝试在方法标题之前放置一个标签,Sphinx就无法识别它.

有没有一种简单的方法可以做到这一点,或者我是否必须在我的类文件中明确地写入方法名称并在其前面添加标签？

这是一个示例[Python文档2中的参考实现我需要的东西(我假设它使用了autodoc功能,虽然我不确定)

我想在C++中为新项目试用文档生成器.我认为我的选择是Doxygen或Sphinx.由于我有Python项目,我想使用Sphinx,我想知道Sphinx是否也是C++的正确选择.该狮身人面像的网站指出,支持C++,但是我找不到让我开始用C++文档的文档.

Stackoverflow上已经讨论过类似的问题,主要答案是:

尚未完全使用,
但继续观看

由于讨论已经超过一年了,我想知道这个结论是否仍然有效.我应该选择Doxygen而不是Sphinx作为我的C++文档吗？

如何将本地目录包含到Sphinx doc中？

我试过了

.. toc:: 

但这似乎没有任何影响:文档中没有插入任何内容.

基本上我需要链接到当前页面中的部分放置在每个页面的特定位置.

这可能吗？

我想在Python文档字符串的其他地方引用先前记录的函数参数.考虑以下(当然是完全人为的)示例:

def foo(bar):
    """Perform foo action
    :param bar: The bar parameter
    """

    def nested():
        """Some nested function that depends on enclosing scope's bar parameter.
        I'd like to reference function foo's bar parameter here
        with a link, is that possible?"""
        return bar * bar

    # ...
    return nested()

是否有一种使用Sphinx标记嵌入参数引用的简单方法,还是会自动发生？

(我是一个完整的Sphinx新手.我一直在扫描Sphinx文档,但没有找到这个问题的答案,或者是一个展示正确标记的例子.)

我正在Sphinx中生成html文档.

如何修改文档中每个html页面的侧边栏,以便它们包含toctree？默认情况下,toctree似乎只显示在master_doc页面中,而且只显示在主区域而不是侧边栏中.

是否有捷径可寻？我将使用readthedocs来托管生成的文档,所以我宁愿避免使用任何第三方插件,除非它们也可以在readthedocs上使用.