可以更改Python autodoc元组/列表格式吗? [英] Can Python autodoc tuple/list format be changed?
问题描述
我要记录的项目中有一些Python代码，但是在记录元组或列表的类常量时遇到了问题. 请参见下面的代码和图像.当每行上有多个项目并且行是随机拆分时，很难阅读文档.
I have some Python code in a project that I want to document, however I have run into a problem with documenting class constants that are tuples or lists. See code and image below. It's very hard to read the documentation when there are several items on each row and the lines are split randomly.
可以用其他方式格式化元组吗?就像新行中的每个元素一样. 我仍然想使用autodoc(在整个文件上)，因此手动添加类是不可接受的. 我可以更改代码，conf.py或自动模块选项.
Can the tuple be formatted in another way? Like each element on a new row. I still want to use autodoc (on the whole file), so manually adding the classes is not acceptable. I can change the code, conf.py or automodule options.
第一个:
.. automodule:: my_python_file
:members:
:undoc-members:
my_python_file.py:
class SOMinimalExample:
"""SO example with ugly formatted tuple"""
MY_CONSTANT = (
('AnElement', (1, 2, 3, 5)),
('AnotherElement', (3, 5)),
('MoreElements', (1, 5)),
('MoreElements', (1, 5, 5)),
('MoreElements', (213, )),
('MoreElements', (5, 1, 5)),
('MoreElements', (1, 8, 5)),
('MoreElements', (1, 0, 0, 0, 5)),
('MoreElements', (1, 123, 4324, 46, 845)),
)
输出:
HTML:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>SO documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="welcome-to-so-s-documentation">
<h1>Welcome to SO’s documentation!<a class="headerlink" href="#welcome-to-so-s-documentation" title="Permalink to this headline">¶</a></h1>
<div class="toctree-wrapper compound">
<span id="document-modules"></span><div class="section" id="so">
<h2>so<a class="headerlink" href="#so" title="Permalink to this headline">¶</a></h2>
<div class="toctree-wrapper compound">
<span id="document-my_python_file"></span><div class="section" id="module-my_python_file">
<span id="my-python-file-module"></span><h3>my_python_file module<a class="headerlink" href="#module-my_python_file" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="my_python_file.SOMinimalExample">
<em class="property">class </em><code class="descclassname">my_python_file.</code><code class="descname">SOMinimalExample</code><a class="headerlink" href="#my_python_file.SOMinimalExample" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></p>
<p>SO example with ugly formatted tuple</p>
<dl class="attribute">
<dt id="my_python_file.SOMinimalExample.MY_CONSTANT">
<code class="descname">MY_CONSTANT</code><em class="property"> = (('AnElement', (1, 2, 3, 5)), ('AnotherElement', (3, 5)), ('MoreElements', (1, 5)), ('MoreElements', (1, 5, 5)), ('MoreElements', (213,)), ('MoreElements', (5, 1, 5)), ('MoreElements', (1, 8, 5)), ('MoreElements', (1, 0, 0, 0, 5)), ('MoreElements', (1, 123, 4324, 46, 845)))</em><a class="headerlink" href="#my_python_file.SOMinimalExample.MY_CONSTANT" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.html#document-index">SO</a></h1>
<h3>Navigation</h3>
<p class="caption"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-modules">so</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html#document-index">Documentation overview</a><ul>
</ul></li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2019, me.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.8.4</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
</div>
</body>
</html>
推荐答案
一种选择是使用autoclass并通过
嵌套 literalinclude 指令.
An option is to use autoclass and pull in the verbatim definition of MY_CONSTANT via a
nested literalinclude directive.
.. autoclass:: my_python_file.SOMinimalExample
:members:
.. attribute:: MY_CONSTANT
Some doc text for MY_CONSTANT.
.. literalinclude:: ../src/my_python_file.py
:dedent: 4
:lines: 3-13
输出:
我希望以下方法能起作用(而不是使用行号):
I was hoping that the following would work (instead of using line numbers):
.. literalinclude:: ../src/my_python_file.py
:pyobject: SOMinimalExample.MY_CONSTANT
但是它不起作用. Sphinx发出警告:在包含文件中找不到名为'SOMinimalExample.MY_CONSTANT'的对象".
But it doesn't work. Sphinx emits a warning: "Object named 'SOMinimalExample.MY_CONSTANT' not found in include file".
这篇关于可以更改Python autodoc元组/列表格式吗?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
