Menu
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.
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.
rst:
.. 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)),
)
Output:
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>
241
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
Output:
I was hoping that the following would work (instead of using line numbers):
.. literalinclude:: ../src/my_python_file.py
:pyobject: SOMinimalExample.MY_CONSTANT
But it doesn't work. Sphinx emits a warning: "Object named 'SOMinimalExample.MY_CONSTANT' not found in include file".
118
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
