标签: python-sphinx

我正在sphinx用来生成我们公司的手册。在我们的传统手册中，我们有某种表格样式，我们希望保留这种样式。

表格样式由具有深绿色背景的表头组成，然后是几行浅绿色背景行，然后是几行白色背景。

Sphinx生成我的 LaTeX 输入文件，然后使用 PdfLatex 将其制作为 PDF。有可能在 LaTeX 表以:raw-role:.

输入 RST 文件：

.. role:: raw-role(raw)
   :format: latex

:raw-role:`\firstRow`   

=== === ===
 A   B   C
=== === ===
1A   1B  1C
2A   2B  2C
3A   3B  3C
4A   4B  4C
=== === ===

将转化为：

\firstRow

\noindent\begin{tabulary}{\linewidth}{|L|L|L|}
\hline
\sphinxstylethead{\relax 
A
\unskip}\relax &\sphinxstylethead{\relax 
B
\unskip}\relax &\sphinxstylethead{\relax 
C
\unskip}\relax \\
\hline
1A
&
1B
&
1C
\\
\hline
2A
&
2B
&
2C
\\
\hline
3A
&
3B …

我想:ref:使用 CSS 类在我的文档中格式化内部链接 - 定义为- 。

我的问题是我无法转换:ref:`Link <internal_link>为以下 HTML<a href="internal_link" class="btn btn-primary btn-sm">Link</a>

我试过定义一个新的，role但也不成功。

.. role:: ref
   :class: btn btn-sm btn-primary

:ref:`Link <internal_link>`

我当前的解决方案是使用原始 html 并按原样呈现它，但我无法链接 RST 文件，而必须指向 HTML 文件（这不适用于 PDF 输出）。

.. role:: raw-html(raw)
   :format: html

:raw-html:`<a href="internal_link.html" class="btn btn-primary btn-sm">Link</a>`

有谁知道如何将自定义 CSS 类添加到:ref:?

我目前正在尝试设置一个 reStructuredText 模板。我想包括编号的数字和对这些数字的引用。所以我遵循了 sphinx 文档（http://www.sphinx-doc.org/en/stable/markup/inline.html）中给出的说明。

首先我包括了这条线

numfig = True

在文件“conf.py”中。我在我的文件“rstTemplate.rst”中实现了这个图和对它的引用，如下所示：

.. _my-figure:

.. figure:: images/scen-smartcity.*
    :scale: 50 %
    :alt: smartcity symbol
    :align: center

    This is the caption of the figure (a simple paragraph).

    This is the legend of the figure

Reference to the figure :numref:`(Fig. %s) my-figure`

当我使用构建 html 文件时 make html

Running Sphinx v1.6.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files …

我在 RTD 上记录了一个 python 模块：http : //modernglextexttools.readthedocs.io

这是另一个模块的扩展，我想在两者之间建立联系。我希望参数和返回类型作为链接工作。这是一个例子。

我的conf.py

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.githubpages',
    'sphinx.ext.intersphinx',    # added this but does not help
    'sphinxcontrib.napoleon'
]

以下是链接外部类的方法示例。外部类是ModernGL.Context. 我不确定是否必须配置此类的记录位置。但它应该指向这个链接。

def load(filename, convert=None, ctx=None) -> ModernGL.Texture:
    '''
        Load a texture. If ctx is ``None`` the default_context is used.

        Args:
            filename (str): The name of the file to load.

        Keyword Args:
            convert (str): Convert the texture before loading. Possible values are: ('L', 'RGB', 'RGBA')
            ctx …

我刚刚将我的文档从 Github 上传到 ReadTheDocs，我发现它在 ReadTheDocs 和我的本地机器上呈现完全不同。我sphinx_rtd_theme在本地机器上使用最新版本。

这是我本地机器上的显示：

这是 ReadTheDocs 上的渲染：

我在 Chrome、Firefox 和 Microsoft Edge 上尝试过，结果相同，所以它似乎不是浏览器问题。

这是我的 conf.py 的副本：

# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these …

我是 Python 和 Sphinx 的新手，正在尝试自动记录位于类似于以下结构的目录中的 python 文件：

Project
??? Sphinx
|   ??? index.rst
|   ??? autodoc.rst
|   ???  conf.py
??? Scripts
|   ??? file1.py
|   ???  file2.py
|   ??? folder
|   |   ??? file3.py

我的 conf.py 文件包含：

sys.path.insert(0, os.path.abspath("../Scripts/"))

和 autodoc 包含：

.. automodule:: file1
  :members:

.. automodule:: file2
  :members:

.. automodule:: folder.file3
  :members:

File3.py 未正确自动记录（错误：没有名为 metric.billpay 的模块）

我也试过：

.. automodule:: folder/file3
  :members:

但我收到

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

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

有谁知道如何解决这一问题？我是 Python、Sphinx 和 StackOverflow 的新手，所以如果这个问题有问题，我深表歉意。

在我的代码中，我有一些复杂的 Enum 类型的类。例如：

class ComplexEnum(SomeOtherClass, Enum):
    """ Some documentation """

    MEMBER1 = SomeOtherClass(1)
    MEMBER2 = SomeOtherClass(2)

    def __init__(self, arg):
        """ more doc """
        pass

    def somemethod(self):
        """ more doc """
        pass

    @classmethod
    def someclassmethod(cls, otherparam):
        """ more doc """
        pass

当我现在使用 autodoc 用 Sphinx 创建我的文档时，这个类被跳过了。我尝试将这样的自定义文档添加到我的 conf.py 文件中：

from sphinx.ext.autodoc import ClassDocumenter

class MyClassDocumenter(ClassDocumenter):
    objtype = 'ComplexEnum'
    directivetype = 'class'

    @classmethod
    def can_document_member(cls, member, membername, isattr, parent):
        return isinstance(member, ComplexEnum)

def setup(app):
    app.add_autodocumenter(MyClassDocumenter)

但这也不起作用。

我怎样才能让 sphinx 记录那些类？

我在rst包含automodule但似乎没有任何效果的文件上运行 Sphinx 。

以下是详细信息：我有一个 Python 项目，其中agent.py包含一个包含类的文件Agent。我还有一个子目录，里面apidoc有一个文件agent.rst（由 生成sphinx-apidoc）：

agent module
============

.. automodule:: agent
   :members:
   :undoc-members:
   :show-inheritance:

我sphinx-build -b html apidoc apidoc/_build使用项目目录作为当前工作目录运行 sphinx 。

为了确保找到 Python 文件，我在 中包含了以下内容apidoc/conf.py：

agent module
============

.. automodule:: agent
   :members:
   :undoc-members:
   :show-inheritance:

它运行时没有错误，但是当我打开生成的 HTML 文件时，它只显示“代理模块”并且一切都是空白的。为什么不显示类Agent及其成员？

更新：最初的问题很可能是由于我没有包含sphinx.ext.autodoc在conf.py. 但是，现在我这样做了，我收到了如下警告：

import os
import sys
sys.path.insert(0, os.path.abspath('.'))

Run Code Online (Sandbox Code Playgroud)

我已经为我想做的大部分事情找到了 sphinx 选项，但是在使用 autodoc 时，我看不到如何在函数签名之间注入空格和水平线。

以下是 autodoc 生成的内容：

get_all_edges(network=None, base_url='http://localhost:1234/v1')
   docstring for get_all_edges

get_all_nodes(network=None, base_url='http://localhost:1234/v1')
   docstring for get_all_nodes

get_edge_count(network=None, base_url='http://localhost:1234/v1')
   docstring for get_edge_count

这是我想要得到的：

get_all_edges(network=None, base_url='http://localhost:1234/v1')
   docstring for get_all_edges

   ------------------------------------------------------------

get_all_nodes(network=None, base_url='http://localhost:1234/v1')
   docstring for get_all_nodes

   ------------------------------------------------------------

get_edge_count(network=None, base_url='http://localhost:1234/v1')
   docstring for get_edge_count

......或接近于此的东西。我对最后一个函数签名是否有尾随分隔符不感兴趣。也许这很简单，但我没有看到。谢谢！

仅供参考，这里是生成我的函数签名的 autodoc 指令：

PyCy3.networks module
---------------------

.. automodule:: PyCy3.networks
    :members:
    :undoc-members:
    :show-inheritance:

使用以下代码，我们可以创建每个最后包含数字的方程。

\documentclass[12pt]{article}
\usepackage{mathtools}
\begin{document}
\begin{align}
    100 + x &= y            \\    
    \frac{y}{x} &\ge 1.3    \\
    (100+x)-(100+x)z &= y 
\end{align}
\end{document}

现在用 python-sphinx 编写它们。

.. math::

    \begin{align}
        100 + x &= y            \\    
        \frac{y}{x} &\ge 1.3    \\
        (100+x)-(100+x)z &= y 
    \end{align}

用 编译后make html，我们得到下图：

您可以看到每行末尾没有数字。
如何在python-sphinx中每行末尾创建带有数字的相同方程？