Code blocks

Code blocks can be easily represented with the code-block directive. Together with Pygments, Sphinx will automatically highlight the syntax. You can specify the appropriate language for a code block with

.. code-block:: LANGUAGE

You can use this for example like this:

.. code-block:: python

   import this



For code-block, the linenos option can also be used to specify that the code block should be displayed with line numbers:

.. code-block:: python

   import this
1import this

Die erste Zeilennummer kann mit der lineno-start-Option ausgewählt werden; linenos wird dann automatisch aktiviert: The first line number can be selected with the lineno-start option; linenos will then be activated automatically:

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

   import antigravity
10import antigravity

emphasize-lines allows you to emphasise individual lines.

.. literalinclude:: FILENAME

allows you to include external files.



Here is an example from our Jupyter-Tutorial:

.. literalinclude::
   :emphasize-lines: 4, 9-12, 20-22
 1from typing import Optional
 3from fastapi import FastAPI
 4from pydantic import BaseModel
 6app = FastAPI()
 9class Item(BaseModel):
10    name: str
11    price: float
12    is_offer: Optional[bool] = None
16def read_root():
17    return {"Hello": "World"}
21def read_item(item_id: int, q: Optional[str] = None):
22    return {"item_id": item_id, "q": q}
26def update_item(item_id: int, item: Item):
27    return {"item_name":, "item_id": item_id}

If you want to show the diff of your code, you can specify the old file with the diff option, for example:

.. literalinclude::
--- /home/docs/checkouts/
+++ /home/docs/checkouts/
@@ -1,8 +1,15 @@
 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
@@ -13,3 +20,8 @@
 def read_item(item_id: int, q: Optional[str] = None):
     return {"item_id": item_id, "q": q}
+def update_item(item_id: int, item: Item):
+    return {"item_name":, "item_id": item_id}

Obsolete code

.. deprecated:: version

Describes when the function became obsolete. An explanation can also be given to inform what should be used instead. For example

.. deprecated:: 4.1
   instead use :func:`new_function`.

Deprecated since version 4.1: instead use new_function().


Marks a Python module as obsolete; it is then marked as such in various places.