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

import 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

import 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:

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}

: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/sphinx/main.py.orig
+++ /home/docs/checkouts/readthedocs.org/user_builds/python-basics-tutorial-de/checkouts/latest/docs/document/sphinx/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.