标签: python-sphinx

我试图使用Sphinx来记录我的Python类.我这样做是使用autodoc:

.. autoclass:: Bus
   :members:

虽然它正确地获取我的方法的文档字符串,那些装饰:

    @checkStale
    def open(self):
        """
        Some docs.
        """
        # Code

与@checkStale存在

def checkStale(f):
    @wraps(f)
    def newf(self, *args, **kwargs):
        if self._stale:
            raise Exception
        return f(self, *args, **kwargs)
    return newf

有一个不正确的原型,如open(*args, **kwargs).

我怎样才能解决这个问题？我的印象是使用@wraps会修复这种事情.

如何在sphinx文档中创建内部超链接？我在用:

:role:`target`  

但它没有用.

我正在使用Sphinx编辑我的项目的文档,而Sphinx又使用reStructuredText作为标记语言.

我有一个简单的表(与网格表相对),其中最右边的列报告包含我想要正确对齐的数字,但我找不到如何实现这一点.

============  =====================
Event               Score variation
============  =====================
Event 1                        +100
Event 2                         -25
Event 3                        -400
============  =====================

如果这可以让我解决问题,我很乐意切换到网格表.

我发现自己有一个用例,除了从基于Sphinx的文档源生成HTML和PDF之外,我还想生成reStructuredText源文件的Markdown版本.

我的初步研究没有在Sphinx中找到任何核心或扩展支持.除了手动使用pandoc或为任务创建新的Sphinx扩展外,是否有更简单/更集成的解决方案？

我想在我的sphinx文档中链接到一些URL:

 <a href="http://some.url">blah</a>

我在文档中找到了类似的东西:http://sphinx-doc.org/ext/extlinks.html - 但它更像是按照惯例用链接替换自定义语法.相反,我只想生成一个指向外部Web资源的链接.

我正在研究共享的Matlab代码,我们希望在本地网络中共享生成的文档作为可搜索的HTML文档.

我知道以下生成文档的方法:

1. 将转换器写入类似C++的文件.这是在使用Doxygen with Matlab(2011年最后更新)和mtoc ++(最后更新2013年)中完成的.然后由Doxygen解析类似C++的文件.
2. 使用Python的sphinxcontrib-matlabdomain生成HTML文档.
3. 使用m2html也是第三方解决方案.
4. 此问答中列出了其他选项:一,二和三.

Mathworks不支持所有可能性.所有可能性都需要我提到自己的函数参数.他们没有分析代码,Doxygen是为Java做的:

//! an object representation of the advertisement package sent by the beacon
private AdvertisementPackage advertisementPackage;

我听说过Matlab的publish()函数,但我从未在上述意义上看到过它.

问题:Mathworks生成Matlab HTML文档的方法是什么.代码本身可以分析吗？我可以使用提供给Matlab输入分析器的信息吗？请在评论中提及您的个人偏好.

例:

%% Input parser
p = inputParser;
addRequired(p, 'x', @isnumeric);

validationFcn = @(x) (isnumeric(x) && isscalar(x));
addRequired(p, 'fftSize', validationFcn);
addRequired(p, 'fftShift', validationFcn);

validationFcn = @(x) (isa(x, 'function_handle'));
addRequired(p, 'analysisWindowHandle', validationFcn);

parse(p, x, fftSize, fftShift, analysisWindowHandle);

我正在使用Sphinx来记录我的python项目.我启用了autodoc扩展,并在我的文档中包含以下内容.

.. autoclass:: ClassName
   :members:

问题是,它只记录了类中的非私有方法.我如何包含私有方法？

我正在尝试使用sphinx autodoc扩展,特别是automodule指令自动生成我正在处理的django app的文档.问题是我想创建模块内不同类的内部引用,而不必在项目中的每个类/函数上使用autoclass和autofunction.对于像这样的源文件:

# source_code.py
class A:
    """docs for A
    """
    pass

class B:
    """docs for B with 
    :ref:`internal reference to A <XXXX-some-reference-to-A-XXXX>`
    """
    pass

我希望能够有一个像这样的sphinx文档文件:

.. automodule: source_code

我可以使用什么参考XXXX-some-reference-to-A-XXXX？有没有一种简单的方法来实现这一目标？在此先感谢您的帮助.

.rst我的Sphinx树中有很多文件被故意排除在任何索引树之外.我收到警告

 /filename.rst:: WARNING: document isn't included in any toctree

如何在Sphinx中抑制特定警告？

因此,reStructuredText是 Python代码文档的推荐方法,如果你足够努力,你可以 在sphinx文档中找到 如何规范化你的函数签名文档.所有给出的示例都是单行的,但是如果参数描述是多行的,如下所示呢？

def f(a, b):
    """ Does something with a and b

    :param a: something simple
    :param b: well, it's not something simple, so it may require more than eighty
              chars
    """

那是什么语法/惯例？我应该缩进吗？它会破坏reSTructuredText渲染吗？