[DOP-13219] Improve documentation

.github/workflows/changelog.yml

@@ -32,9 +32,6 @@ jobs:
 
       - name: Install poetry
         uses: snok/install-poetry@v1
-        with:
-          virtualenvs-create: true
-          virtualenvs-in-project: true
 
       - name: Cache poetry
         uses: actions/cache@v4
@@ -59,7 +56,7 @@ jobs:
           fi
 
       - name: Validate changelog
-        run: |-
+        run: |
           # Fetch the pull request' base branch so towncrier will be able to
           # compare the current branch with the base branch.
           git fetch --no-tags origin +refs/heads/${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}

.github/workflows/codeql-analysis.yml

@@ -41,9 +41,6 @@ jobs:
 
       - name: Install poetry
         uses: snok/install-poetry@v1
-        with:
-          virtualenvs-create: true
-          virtualenvs-in-project: true
 
       - name: Cache poetry
         uses: actions/cache@v4
@@ -61,10 +58,10 @@ jobs:
           poetry install --no-root --all-extras --with dev --without docs,test
 
       - name: Run flake8
-        run: poetry run flake8 horizon/
+        run: flake8 horizon/
 
       - name: Run mypy
-        run: poetry run mypy ./horizon --config-file ./pyproject.toml
+        run: mypy ./horizon --config-file ./pyproject.toml
 
   codeql:
     name: CodeQL

.github/workflows/dev-release.yaml

@@ -39,9 +39,6 @@ jobs:
 
       - name: Install poetry
         uses: snok/install-poetry@v1
-        with:
-          virtualenvs-create: true
-          virtualenvs-in-project: true
 
       - name: Generate unique version and update test version
         run: |

.github/workflows/release.yml

@@ -37,9 +37,6 @@ jobs:
 
       - name: Install poetry
         uses: snok/install-poetry@v1
-        with:
-          virtualenvs-create: true
-          virtualenvs-in-project: true
 
       - name: Cache poetry
         uses: actions/cache@v4
@@ -53,7 +50,7 @@ jobs:
       - name: Generate OpenAPI Schema
         run: |
           source .env.local
-          poetry run python -m horizon.backend.export_openapi_schema openapi.json
+          python -m horizon.backend.export_openapi_schema openapi.json
 
       - name: Fix logo in Readme
         run: |

docs/backend/configuration/debug.rst

@@ -11,12 +11,11 @@ to avoid exposing instance-specific information to end users.
 
 You can change this by setting:
 
-.. code-block:: bash
-
-    >>> export HORIZON__SERVER__DEBUG=False
-    >>> # start backend
-    >>> curl -XPOST http://localhost:8000/failing/endpoint ...
+.. code-block:: console
 
+    $ export HORIZON__SERVER__DEBUG=False
+    $ # start backend
+    $ curl -XPOST http://localhost:8000/failing/endpoint ...
     {
         "error": {
             "code": "unknown",
@@ -25,12 +24,11 @@ You can change this by setting:
         },
     }
 
-.. code-block:: bash
-
-    >>> export HORIZON__SERVER__DEBUG=True
-    >>> # start backend
-    >>> curl -XPOST http://localhost:8000/failing/endpoint ...
+.. code-block:: console
 
+    $ export HORIZON__SERVER__DEBUG=True
+    $ # start backend
+    $ curl -XPOST http://localhost:8000/failing/endpoint ...
     Traceback (most recent call last):
     File ".../uvicorn/protocols/http/h11_impl.py", line 408, in run_asgi
         result = await app(  # type: ignore[func-returns-value]
@@ -68,7 +66,7 @@ This is done by adding a specific filter to logging handler:
 
 Resulting logs look like:
 
-.. code-block::
+.. code-block:: text
 
     2023-12-18 17:14:11.711 uvicorn.access:498 [INFO] 018c15e97a068ae09484f8c25e2799dd 127.0.0.1:34884 - "GET /monitoring/ping HTTP/1.1" 200
 
@@ -78,28 +76,17 @@ Use ``X-Request-ID`` header on client
 
 If client got ``X-Request-ID`` header from backend, it is printed to logs with ``DEBUG`` level:
 
-.. code-block:: python
-
-    import logging
-
-    logging.basicConfig(level=logging.DEBUG)
-    client.ping()
-
-.. code-block:: text
-
-    DEBUG:urllib3.connectionpool:http://localhost:8000 "GET /monitoring/ping HTTP/1.1" 200 15
-    DEBUG:horizon.client.base:Request ID: '018c15e97a068ae09484f8c25e2799dd'
+>>> import logging
+>>> logging.basicConfig(level=logging.DEBUG)
+>>> client.ping()
+DEBUG:urllib3.connectionpool:http://localhost:8000 "GET /monitoring/ping HTTP/1.1" 200 15
+DEBUG:horizon.client.base:Request ID: '018c15e97a068ae09484f8c25e2799dd'
 
 Also, if backend response was not successful, ``Request ID`` is added to exception message:
 
-.. code-block:: python
-
-    client.get_namespace("unknown")
-
-.. code-block:: text
-
-    requests.exceptions.HTTPError: 404 Client Error: Not Found for url: http://localhost:8000/v1/namespaces/unknown
-    Request ID: '018c15eb80fa81a6b38c9eaa519cd322'
+>>> client.get_namespace("unknown")
+requests.exceptions.HTTPError: 404 Client Error: Not Found for url: http://localhost:8000/v1/namespaces/unknown
+Request ID: '018c15eb80fa81a6b38c9eaa519cd322'
 
 
 Fill up ``X-Application-Version`` header on backend
@@ -119,10 +106,5 @@ If client got ``X-Application-Version`` header from backend, it is compared with
 
 If versions do not match, a warning is shown:
 
-.. code-block:: python
-
-    client.ping()
-
-.. code-block:: text
-
-    UserWarning: Horizon client version '0.0.9' does not match backend version '1.0.0'. Please upgrade.
+>>> client.ping()
+UserWarning: Horizon client version '0.0.9' does not match backend version '1.0.0'. Please upgrade.

docs/backend/install.rst

@@ -44,9 +44,9 @@ Installation process
 
 Install ``data-horizon`` package with following *extra* dependencies:
 
-.. code-block:: bash
+.. code-block:: console
 
-    pip install data-horizon[backend,postgres,ldap]
+    $ pip install data-horizon[backend,postgres,ldap]
 
 Available *extras* are:
 
@@ -65,7 +65,7 @@ Start Postgres instance somewhere, and set up database url using environment var
 
 .. code-block:: bash
 
-    export HORIZON__DATABASE__URL=postgresql+asyncpg://user:password@postgres-host:5432/database_name
+    HORIZON__DATABASE__URL=postgresql+asyncpg://user:password@postgres-host:5432/database_name
 
 You can use virtually any database supported by `SQLAlchemy <https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls>`_,
 but the only one we really tested is Postgres.
@@ -77,9 +77,9 @@ Run migrations
 
 To apply migrations (database structure changes) you need to execute following command:
 
-.. code-block:: bash
+.. code-block:: console
 
-    python -m horizon.backend.db.migrations upgrade head
+    $ python -m horizon.backend.db.migrations upgrade head
 
 This is a thin wrapper around `alembic <https://alembic.sqlalchemy.org/en/latest/tutorial.html#running-our-first-migration>`_ cli,
 options and commands are just the same.
@@ -93,9 +93,9 @@ Run backend
 
 To start backend server you need to execute following command:
 
-.. code-block:: bash
+.. code-block:: console
 
-    python -m horizon.backend --host 0.0.0.0 --port 8000
+    $ python -m horizon.backend --host 0.0.0.0 --port 8000
 
 This is a thin wrapper around `uvicorn <https://www.uvicorn.org/#command-line-options>`_ cli,
 options and commands are just the same.

docs/changelog/next_release/20.improvements.rst

@@ -0,0 +1,3 @@
+Fix documentation examples.
+
+Make documentation more user-friendly.

docs/client/install.rst

@@ -14,9 +14,9 @@ Installation process
 
 Install ``data-horizon`` package with following *extra* dependencies:
 
-.. code-block:: bash
+.. code-block:: console
 
-    pip install data-horizon[client-sync]
+    $ pip install data-horizon[client-sync]
 
 Available *extras* are:
 

docs/client/sync.rst

@@ -8,38 +8,68 @@ Quickstart
 
 Here is a short example of using sync client to interact with backend.
 
-.. code-block:: python
-
-    from horizon.client.sync import HorizonClientSync
-    from horizon.client.auth import LoginPassword
-    from horizon.commons.schemas.v1 import NamespaceCreateRequestV1, HWMUpdateRequestV1
-
-    # create client object
-    client = HorizonClientSync(
-        base_url="http://some.domain.com/api",
-        auth=LoginPassword(login="me", password="12345"),
-    )
-
-    # check for credentials and issue access token
-    client.authorize()
-
-    # create namespace with name "my_namespace"
-    created_namespace = client.create_namespace(
-        NamespaceCreateRequestV1(name="my_namespace"),
-    )
-
-    # create HWM with name "my_hwm" in this namespace
-    hwm = HWMCreateRequestV1(
-        namespace_id=created_namespace.id,
-        name="my_hwm",
-        type="column_int",
-        value=123,
-    )
-    created_hwm = client.create_hwm(hwm)
-
-    # update HWM with name "my_hwm" in this namespace
-    hwm_change = HWMUpdateRequestV1(value=234)
-    updated_hwm = client.update_hwm(hwm.id, hwm_change)
+Create client object:
+
+>>> from horizon.client.sync import HorizonClientSync
+>>> from horizon.client.auth import LoginPassword
+>>> client = HorizonClientSync(
+...     base_url="http://some.domain.com/api",
+...     auth=LoginPassword(login="me", password="12345"),
+... )
+
+Check for credentials and issue access token:
+
+>>> client.authorize()
+
+Create namespace with name "my_namespace":
+
+>>> from horizon.commons.schemas.v1 import NamespaceCreateRequestV1
+>>> created_namespace = client.create_namespace(NamespaceCreateRequestV1(name="my_namespace"))
+>>> created_namespace
+NamespaceResponseV1(
+    id=1,
+    name="my_namespace",
+    description="",
+)
+
+Create HWM with name "my_hwm" in this namespace:
+
+>>> from horizon.commons.schemas.v1 import HWMCreateRequestV1
+>>> hwm = HWMCreateRequestV1(
+...     namespace_id=created_namespace.id,
+...     name="my_hwm",
+...     type="column_int",
+...     value=123,
+... )
+>>> created_hwm = client.create_hwm(hwm)
+>>> created_hwm
+HWMResponseV1(
+    id=1,
+    namespace_id=1,
+    name="my_hwm",
+    description="",
+    type="column_int",
+    value=123,
+    entity="",
+    expression="",
+)
+
+Update HWM with name "my_hwm" in this namespace:
+
+>>> from horizon.commons.schemas.v1 import HWMUpdateRequestV1
+>>> hwm_change = HWMUpdateRequestV1(value=234)
+>>> updated_hwm = client.update_hwm(created_hwm.id, hwm_change)
+>>> updated_hwm
+HWMResponseV1(
+    id=1,
+    namespace_id=1,
+    name="my_hwm",
+    description="",
+    type="column_int",
+    value=234,
+    entity="",
+    expression="",
+)
 
 Reference
 ---------

docs/conf.py

@@ -47,6 +47,7 @@
 extensions = [
     "numpydoc",
     "sphinx_copybutton",
+    "sphinx.ext.doctest",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
@@ -85,6 +86,10 @@
 autodoc_pydantic_field_list_validators = False
 sphinx_tabs_disable_tab_closing = True
 
+# prevent >>>, ... and doctest outputs from copying
+copybutton_exclude = ".linenos, .gp, .go"
+copybutton_copy_empty_lines = False
+
 towncrier_draft_autoversion_mode = "draft"
 towncrier_draft_include_empty = False
 towncrier_draft_working_directory = PROJECT_ROOT_DIR

horizon/backend/settings/server/log/__init__.py

@@ -35,8 +35,8 @@ class LoggingSettings(BaseModel):
 
     .. code-block:: bash
 
-        export HORIZON__SERVER__LOGGING__SETUP=False
-        python -m horizon.backend --log-level debug
+        $ export HORIZON__SERVER__LOGGING__SETUP=False
+        $ python -m horizon.backend --log-level debug
     """
 
     setup: bool = Field(

horizon/client/auth/access_token.py

@@ -25,11 +25,8 @@ class AccessToken(BaseAuth, BaseModel):
     Examples
     --------
 
-    .. code-block:: python
-
-        from horizon.client.auth import AccessToken
-
-        auth = AccessToken(token="my.access.token")
+    >>> from horizon.client.auth import AccessToken
+    >>> auth = AccessToken(token="my.access.token")
     """
 
     token: str

horizon/client/auth/login_password.py

@@ -28,11 +28,8 @@ class LoginPassword(BaseAuth, BaseModel):
     Examples
     --------
 
-    .. code-block:: python
-
-        from horizon.client.auth import LoginPassword
-
-        auth = LoginPassword(login="me", password="12345")
+    >>> from horizon.client.auth import LoginPassword
+    >>> auth = LoginPassword(login="me", password="12345")
     """
 
     login: str