Can Python autodoc tuple/list format be changed?

问题

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">
      &copy;2019, me.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.8.4</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
    </div>
  </body>
</html>

回答1:

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:

Sphinx 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".

来源：https://stackoverflow.com/questions/54823758/can-python-autodoc-tuple-list-format-be-changed

标签

python

python-sphinx

autodoc