[DOP-13219] Improve documentation

docs/backend/configuration/debug.rst

@@ -11,7 +11,7 @@ to avoid exposing instance-specific information to end users.
 
 You can change this by setting:
 
-.. code-block:: bash
+.. code-block:: console
 
     >>> export HORIZON__SERVER__DEBUG=False
     >>> # start backend
@@ -25,7 +25,7 @@ You can change this by setting:
         },
     }
 
-.. code-block:: bash
+.. code-block:: console
 
     >>> export HORIZON__SERVER__DEBUG=True
     >>> # start backend
@@ -68,7 +68,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 +78,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 +108,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,7 +44,7 @@ Installation process
 
 Install ``data-horizon`` package with following *extra* dependencies:
 
-.. code-block:: bash
+.. code-block:: console
 
     pip install data-horizon[backend,postgres,ldap]
 
@@ -63,7 +63,7 @@ Run database
 
 Start Postgres instance somewhere, and set up database url using environment variables:
 
-.. code-block:: bash
+.. code-block:: console
 
     export HORIZON__DATABASE__URL=postgresql+asyncpg://user:password@postgres-host:5432/database_name
 
@@ -77,7 +77,7 @@ 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
 
@@ -93,7 +93,7 @@ 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
 

docs/changelog/next_release/20.improvement.rst

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

docs/client/install.rst

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

docs/client/sync.rst

@@ -8,38 +8,66 @@ 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)
+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)
+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/__init__.py

@@ -30,7 +30,7 @@ class Settings(BaseSettings):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         # same as settings.database.url = "postgresql+asyncpg://postgres:postgres@localhost:5432/horizon"
         HORIZON__DATABASE__URL=postgresql+asyncpg://postgres:postgres@localhost:5432/horizon

horizon/backend/settings/auth/__init__.py

@@ -19,7 +19,7 @@ class AuthSettings(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         # set settings.auth.provider = horizon.backend.providers.auth.dummy.DummyAuthProvider
         HORIZON__AUTH__PROVIDER=horizon.backend.providers.auth.dummy.DummyAuthProvider

horizon/backend/settings/auth/cached_ldap.py

@@ -21,7 +21,7 @@ class LDAPCachePasswordHashSettings(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__AUTH__CACHE__PASSWORD_HASH__ALGORITHM=argon2
         HORIZON__AUTH__CACHE__PASSWORD_HASH__OPTIONS={"time_cost": 2, "memory_cost": 1024, "parallelism": 1}
@@ -50,7 +50,7 @@ class LDAPCacheSettings(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__AUTH__CACHE__EXPIRE_SECONDS=3600  # 1 hour
     """
@@ -79,7 +79,7 @@ class CachedLDAPAuthProviderSettings(LDAPAuthProviderSettings):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__AUTH__PROVIDER=horizon.backend.providers.auth.cached_ldap.CachedLDAPAuthProvider
         HORIZON__AUTH__ACCESS_KEY__SECRET_KEY=secret

horizon/backend/settings/auth/dummy.py

@@ -11,7 +11,7 @@ class DummyAuthProviderSettings(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__AUTH__PROVIDER=horizon.backend.providers.auth.dummy.DummyAuthProvider
         HORIZON__AUTH__ACCESS_KEY__SECRET_KEY=secret

horizon/backend/settings/auth/jwt.py

@@ -12,7 +12,7 @@ class JWTSettings(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__AUTH__ACCESS_KEY__SECRET_KEY=somesecret
         HORIZON__AUTH__ACCESS_KEY__EXPIRE_SECONDS=3600  # 1 hour

horizon/backend/settings/auth/ldap.py

@@ -44,7 +44,7 @@ class LDAPCredentials(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__AUTH__LDAP__LOOKUP__CREDENTIALS__USER=uid=techuser,ou=users,dc=example,dc=com
         HORIZON__AUTH__LDAP__LOOKUP__CREDENTIALS__PASSWORD=somepassword
@@ -64,7 +64,7 @@ class LDAPConnectionPoolSettings(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__AUTH__LDAP__LOOKUP__POOL__ENABLED=True
         HORIZON__AUTH__LDAP__LOOKUP__POOL__MAX=10
@@ -91,7 +91,7 @@ class LDAPLookupSettings(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__AUTH__LDAP__LOOKUP__ENABLED=True
         HORIZON__AUTH__LDAP__LOOKUP__POOL__ENABLED=True
@@ -156,7 +156,7 @@ class LDAPSettings(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__AUTH__LDAP__URL=ldap://ldap.domain.com:389
         HORIZON__AUTH__LDAP__UID_ATTRIBUTE=sAMAccountName
@@ -212,7 +212,7 @@ class LDAPAuthProviderSettings(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__AUTH__PROVIDER=horizon.backend.providers.auth.ldap.LDAPAuthProvider
         HORIZON__AUTH__ACCESS_KEY__SECRET_KEY=secret

horizon/backend/settings/database.py

@@ -18,7 +18,7 @@ class DatabaseSettings(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__DATABASE__URL=postgresql+asyncpg://postgres:postgres@localhost:5432/horizon
         # custom option passed directly to engine factory

horizon/backend/settings/server/__init__.py

@@ -22,7 +22,7 @@ class ServerSettings(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__SERVER__DEBUG=True
         HORIZON__SERVER__LOGGING__PRESET=colored

horizon/backend/settings/server/application_version.py

@@ -10,7 +10,7 @@ class ApplicationVersionSettings(BaseModel):
     Examples
     --------
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__SERVER__APPLICATION_VERSION__ENABLED=True
         HORIZON__SERVER__APPLICATION_VERSION__HEADER_NAME=X-Application-Version

horizon/backend/settings/server/cors.py

@@ -21,7 +21,7 @@ class CORSSettings(BaseModel):
 
     For development environment:
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__SERVER__CORS__ENABLED=True
         HORIZON__SERVER__CORS__ALLOW_ORIGINS=["*"]
@@ -31,7 +31,7 @@ class CORSSettings(BaseModel):
 
     For production environment:
 
-    .. code-block:: bash
+    .. code-block:: console
 
         HORIZON__SERVER__CORS__ENABLED=True
         HORIZON__SERVER__CORS__ALLOW_ORIGINS=["production.example.com"]