Code-Blöcke#

Code-Blöcke lassen sich mit der Direktive code-block sehr einfach darstellen. Zusammen mit Pygments hebt Sphinx dann die jeweilige Syntax automatisch hervor. Die passende Sprache für einen Code-Block könnt ihr angeben mit

.. code-block:: LANGUAGE#

Ihr könnt dies z.B. so verwenden:

.. code-block:: python

   import this

Optionen

:linenos:#

Für code-block kann mit der linenos-Option auch angegeben werden, dass der Code-Block mit Zeilennummern angezeigt werden soll:

.. code-block:: python
   :linenos:

   import this
1import this
:lineno-start:#

Die erste Zeilennummer kann mit der lineno-start-Option ausgewählt werden; linenos wird dann automatisch aktiviert:

.. code-block:: python
   :lineno-start: 10

   import antigravity
10import antigravity
:emphasize-lines:#

emphasize-lines erlaubt euch, einzelne Zeilen hervorzuheben.

.. literalinclude:: FILENAME#

erlaubt euch, externe Dateien einzubinden.

Optionen

:emphasize-lines:#
:linenos:#

Hier ein Beispiel aus unserem Jupyter-Tutorial:

.. literalinclude:: main.py
   :emphasize-lines: 4, 9-12, 20-22
   :linenos:
 1from typing import Optional
 2
 3from fastapi import FastAPI
 4from pydantic import BaseModel
 5
 6app = FastAPI()
 7
 8
 9class Item(BaseModel):
10    name: str
11    price: float
12    is_offer: Optional[bool] = None
13
14
15@app.get("/")
16def read_root():
17    return {"Hello": "World"}
18
19
20@app.get("/items/{item_id}")
21def read_item(item_id: int, q: Optional[str] = None):
22    return {"item_id": item_id, "q": q}
23
24
25@app.put("/items/{item_id}")
26def update_item(item_id: int, item: Item):
27    return {"item_name": item.name, "item_id": item_id}
:diff:#

Wenn ihr das Diff eures Codes anzeigen möchtet, könnt ihr die alte Datei mit der diff-Option angeben, z.B.:

.. literalinclude:: main.py
   :diff: main.py.orig
--- /home/docs/checkouts/readthedocs.org/user_builds/python-basics-tutorial-de/checkouts/latest/docs/document/main.py.orig
+++ /home/docs/checkouts/readthedocs.org/user_builds/python-basics-tutorial-de/checkouts/latest/docs/document/main.py
@@ -1,12 +1,27 @@
 from typing import Optional
+
 from fastapi import FastAPI
+from pydantic import BaseModel
 
 app = FastAPI()
+
+
+class Item(BaseModel):
+    name: str
+    price: float
+    is_offer: Optional[bool] = None
+
 
 @app.get("/")
 def read_root():
     return {"Hello": "World"}
 
+
 @app.get("/items/{item_id}")
 def read_item(item_id: int, q: Optional[str] = None):
     return {"item_id": item_id, "q": q}
+
+
+@app.put("/items/{item_id}")
+def update_item(item_id: int, item: Item):
+    return {"item_name": item.name, "item_id": item_id}

Veralteter Code#

.. deprecated:: version#

Beschreibt, wann die Funktion veraltet wurde. Es kann auch eine Erklärung angegeben werden, um z.B. darüber zu informieren, was stattdessen verwendet werden sollte. Beispiel:

.. deprecated:: 4.1
   verwende stattdessen :func:`new_function`.

Veraltet ab Version 4.1: verwende stattdessen new_function().

:py:module:deprecated:#

Markiert ein Python-Modul als veraltet; es wird dann an verschiedenen Stellen als solches gekennzeichnet.