zur Zeit häufen sich wieder die Probleme. Da mein Kopf gerade echt voll ist, dachte ich, ich nutze mal Sphinx und schau was mir das für eine schöne Doku zaubert. Ich hatte das noch im Hinterkopf, dass das automatisch meine Doc-Strings nimmt und auf HTML-Seiten darstellt. In der Doku dazu wird das auch so beschrieben, bei mir wird aber zu wenig dargestellt.
Dazu habe ich wieder ein Minimal-Beispiel erstellt, an dem ich gut zeigen kann was ich erwarte.
Das Ganze auf Github oder die wichtigsten Infos hier:
Meine Project-Struktur:
Code: Alles auswählen
(.venv) [dennis@dennis Doc-Testing]$ tree -L 3
.
├── app
│ └── src
│ ├── cool_code.py
│ ├── __init__.py
│ └── __pycache__
└── docs
├── build
│ ├── doctrees
│ └── html
├── make.bat
├── Makefile
└── source
├── api.rst
├── conf.py
├── generated
├── index.rst
├── _static
└── _templates
12 directories, 7 files
Code: Alles auswählen
from attrs import define, field
@define(frozen=True)
class Box:
"""
Represent a Box. A Box is a super magic thing, even I don't know what it is.
:type content: int
:param content: The number you want to put into the box.
"""
content = field()
def get_box_output(self, some_magic):
"""
Depending on the box content and the given magic, the output will be generated.
:type some_magic: float
:param some_magic: The super special extra
:return: The box output as float
"""
return self.content * some_magic
Code: Alles auswählen
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parents[2] / "app/src"))
project = 'Testing'
copyright = '2025, Dennis'
author = 'Dennis'
extensions = [
'sphinx.ext.duration',
'sphinx.ext.autodoc',
'sphinx.ext.autosummary'
]
autosummary_generate = True
templates_path = ['_templates']
exclude_patterns = []
html_theme = 'alabaster'
html_static_path = ['_static']
Code: Alles auswählen
Testing documentation
=====================
Some bla bla
.. toctree::
:maxdepth: 2
:caption: Contents:
Contents
--------
.. toctree::
apiCode: Alles auswählen
API
===
.. autosummary::
:toctree: generated
:recursive:
cool_codeCode: Alles auswählen
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>API — Testing documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=5ecbeea2" />
<link rel="stylesheet" type="text/css" href="_static/basic.css?v=b08954a9" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=27fed22d" />
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="cool_code" href="generated/cool_code.html" />
<link rel="prev" title="Testing documentation" href="index.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="api">
<h1>API<a class="headerlink" href="#api" title="Link to this heading">¶</a></h1>
<table class="autosummary longtable docutils align-default">
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="generated/cool_code.html#module-cool_code" title="cool_code"><code class="xref py py-obj docutils literal notranslate"><span class="pre">cool_code</span></code></a></p></td>
<td><p></p></td>
</tr>
</tbody>
</table>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.html">Testing</a></h1>
<search id="searchbox" style="display: none" role="search">
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">API</a><ul>
<li class="toctree-l2"><a class="reference internal" href="generated/cool_code.html">cool_code</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="index.html" title="previous chapter">Testing documentation</a></li>
<li>Next: <a href="generated/cool_code.html" title="next chapter">cool_code</a></li>
</ul></li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2025, Dennis.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
|
<a href="_sources/api.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>Mache ich hier einen grundsätzlichen Fehler? Macht `autosummary` einfach nicht das was ich erwarte und ich muss jede Funktion mit `autodoc` seperat ansprechen? Soweit wie ich das verstanden habe, sollte `autosummary` mir das abnehmen.
Wenn ich eine Funktion/Mehtode mit `autodoc` anspreche, dann sieht das Ergebnis für diese Funktion/Mehtode aus wie erwartet. Daher gehe ich davon aus, dass die Doc-Strings von der Art und Syntax passen.
Danke und Grüße
Dennis