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: 3,7-10,20-22
   :linenos:
 1from typing import Optional
 2from fastapi import FastAPI
 3from pydantic import BaseModel
 4
 5app = FastAPI()
 6
 7 class Item(BaseModel):
 8     name: str
 9     price: float
10     is_offer: Optional[bool] = None
11
12@app.get("/")
13def read_root():
14    return {"Hello": "World"}
15
16@app.get("/items/{item_id}")
17def read_item(item_id: int, q: Optional[str] = None):
18    return {"item_id": item_id, "q": q}
19
20 @app.put("/items/{item_id}")
21 def update_item(item_id: int, item: Item):
22     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,7 +1,13 @@
 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():
@@ -10,3 +16,7 @@
 @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.