标签: python-sphinx

我想从同一个类的另一个方法的docstring中添加一个到我的类中的方法的链接.我希望链接在sphinx中工作,并且优先在Spyder和其他Python IDE中工作.

我尝试了几个选项,发现只有一个可行,但它很麻烦.

假设以下结构 mymodule.py

def class MyClass():
    def foo(self):
        print 'foo'
    def bar(self):
        """This method does the same as <link to foo>"""
        print 'foo'

我尝试了以下选项<link to foo>:

• :FUNC:`foo`
• :FUNC:`self.foo`
• :FUNC:`MyClass.foo`
• :FUNC:`mymodule.MyClass.foo`

有效生成链接的唯一一个是:func:`mymodule.MyClass.foo`,但链接显示为mymodule.MyClass.foo(),我想要一个显示为foo()或的链接foo.
上述选项均未在Spyder中生成链接.

谢谢你的帮助.

我已经添加了关于在软件包之间设置Sphinx文档链接的文档

intersphinx_mapping = {'python': ('http://docs.python.org/2', None),
                       'numpy': ('http://docs.scipy.org/doc/numpy/', None),
                       'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
                       'matplotlib': ('http://matplotlib.sourceforge.net/', None)}

到我的conf.py,但似乎无法获得除Python本身以外的任何项目的链接.例如

:term:`svg graphics <matplotlib:svg>`

只需将我带到索引页面,而不添加预期的#term-svg锚点,我甚至无法找到词汇表scipy或找出如何确定包所支持的:ref:s或:term:s.

我在哪里可以找到如何指定目标指令:ref:S和:term:S IN numpy,scipy和matplotlib？

就此而言,我如何链接到Sphinx本身？添加

intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', None)

和

:ref:`Intersphinx <intersphinx>`

不起作用.

我正在制作一个框架,让开发人员使用reStructuredText描述他们的包.我想将reStructuredText解析为HTML,以便我可以在GUI中显示它.

我熟悉优秀的Sphinx,但我从来没有解析过reStructuredText.我想象了一个函数,它接受一串reStructuredText,可能还有几个额外的参数,并返回一个HTML字符串.

所以我查看了Docutils,它负责解析reStructuredText.我根本无法理解如何找到这个功能.网上的文档很多.该docutils.parsers.rst模块中的许多功能似乎都面向文件名.我没有文件名!我只是处理字符串.

我尝试创建一个Parser和一个Document并使用该parse方法,但我只是得到一个错误的.tab_width设置错误.

有谁知道如何将reStructuredText解析为HTML？

我很快就开始了一个开源Python项目,我正在尝试提前决定如何编写我的文档字符串.显而易见的答案是使用reStructuredText和Sphinx与autodoc,因为我真的喜欢简单地在我的文档字符串中正确记录我的代码然后让Sphinx为我自动构建API文档.

问题是它使用的reStructuredText语法 - 我认为它在呈现之前是完全不可读的.例如:

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File instance
    is destructed
:type temporary: bool

你必须真正放慢脚步,花一点时间才能理解这种语法混乱.我更喜欢谷歌方式(谷歌Python风格指南),与上面的对应方式如下:

Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The FileStorage instance to wrap
    temporary (bool): Whether or not to delete the file when the File …

我正在尝试使用Sphinx为我的代码库自动生成基本文档.但是,我很难指示Sphinx递归扫描我的文件.

我有一个Python代码库,其文件夹结构如下:

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2

我运行了sphinx-quickstart <workspace>,所以现在我的结构看起来像:

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2
    index.rst
    _build
    _static
    _templates

我已经阅读了快速入门教程http://sphinx.pocoo.org/tutorial.html,虽然我仍在尝试理解文档,但它的措辞让我担心Sphinx会假设我要手动创建我的代码库中每个模块/类/函数的文档文件.

但是,我确实注意到了"automodule"语句,并且我在快速入门期间启用了autodoc,所以我希望大多数文档都可以自动生成.我修改了我的conf.py来将我的src文件夹添加到sys.path然后修改我的index.rst以使用自动模块.所以现在我的index.rst看起来像:

Contents:

.. toctree::
   :maxdepth: 2

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

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

.. automodule:: alphabuyer
   :members:

我在子包中定义了几十个类和函数.然而,当我跑:

sphinx-build -b html . ./_build

它报道:

updating environment: 1 added, 0 changed, 0 removed

这似乎无法导入我的包内的任何东西.查看生成的index.html在"Contents:"旁边没有显示任何内容.索引页面仅显示"mypackage(模块)",但单击它显示它也没有内容.

如何指导Sphinx递归解析包并自动生成它遇到的每个类/方法/函数的文档,而不必自己手动列出每个类？

我收到了警告:

WARNING: document isn't included in any toctree

对于文档中存在的文件,因为它们已被明确包含在内.所以我有索引文件:

.. toctree::
    :maxdepth: 2

   pages/0010-foo
   pages/0020-bar

在0020-bar.rst文件中,我特别包含了许多其他文件,如:

.. contents:: :local:

.. include:: /pages/reference-architecture/technical-considerations/0070-baz.rst

但是当我构建项目时,我仍然会收到警告:0070-baz.rst不在任何toctree中,如:

/home/nick/Documents/myProject/docs/pages/reference-architecture/technical-considerations/0070-baz.rst:: WARNING: document isn't included in any toctree

奇怪的是我可以看到输出中的内容.这是正常的吗？对于明确包含但不包含在toctree中的文件,是否始终显示此警告？

谢谢!

我有一个模块,errors.py其中定义了几个全局常量(注意:我知道Python没有常量,但我已经使用UPPERCASE按惯例定义了它们).

"""Indicates some unknown error."""
API_ERROR = 1

"""Indicates that the request was bad in some way."""
BAD_REQUEST = 2

"""Indicates that the request is missing required parameters."""
MISSING_PARAMS = 3

使用reStructuredText如何记录这些常量？正如你所看到的,我已经在他们上面列出了一个文档字符串,但我没有找到任何表明这样做的文档,我只是猜测它.

如何使用Sphinx-Napoleon为Google风格的文档字符串指示生成器的列表,可选参数和返回类型的类型？

我试过了

List[type]
list of type

Optional[type]
type, optional

和

Yields:
   type: 

分别; 但是所有产生的输出都不令人满意,与生成的文档的其余部分不一致.例如

Optional[type]

只是给

可选[类型]

没有任何链接type.

我尝试过每个内置主题并遇到同样的问题.

我应该如何使用Sphinx-Napoleon的Google风格文档来记录这些元素？

我正在使用Sphinx为python项目生成文档.输出html不保留docstring中存在的换行符.例:

码

def testMethod(arg1,arg2):
    """
    This is a test method

    Arguments:
    arg1: arg1 description
    arg2: arg2 description

    Returns:
    None
    """
    print "I am a test method"

狮身人面像O/P:

TestModule.testMethod(arg1, arg2)

This is a test method

Arguments: arg1: arg1 description arg2: arg2 description

Returns: None

知道怎么解决吗？

第一次尝试使用Sphinx,使用干净的Sphinx 1.1.3安装,shinx-quickstart失败.是否应该安装任何依赖项？我试过,pip --force-reinstall sphinx但结果是一样的.

  myhost:doc anton$ sphinx-quickstart 
  Traceback (most recent call last):
  File "/usr/local/bin/sphinx-quickstart", line 8, in <module>
    load_entry_point('Sphinx==1.1.3', 'console_scripts', 'sphinx-quickstart')()
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/Extras/lib/python/pkg_resources.py", line 318, in load_entry_point
    return get_distribution(dist).load_entry_point(group, name)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/Extras/lib/python/pkg_resources.py", line 2221, in load_entry_point
    return ep.load()
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/Extras/lib/python/pkg_resources.py", line 1954, in load
    entry = __import__(self.module_name, globals(),globals(), ['__name__'])
  File "/Library/Python/2.7/site-packages/Sphinx-1.1.3-py2.7.egg/sphinx/quickstart.py", line 19, in <module>
    from sphinx.util.osutil import make_filename
  File "/Library/Python/2.7/site-packages/Sphinx-1.1.3-py2.7.egg/sphinx/util/__init__.py", line 25, in <module>
    from docutils.utils import relative_path
  File "/Library/Python/2.7/site-packages/docutils-0.9-py2.7.egg/docutils/utils/__init__.py", line 19, in <module>
    from docutils.io import …