Improve docs

.pre-commit-config.yaml

@@ -64,3 +64,9 @@ repos:
         pass_filenames: false
         types: [python]
         stages: [pre-push]
+      - id: doc_build_verify
+        name: verify that docs could be build
+        entry: inv docs.build
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

HISTORY.rst

@@ -6,7 +6,7 @@ UNRELEASED
 ------------------
 
 * Add explicit `created_by` argument to `CeleryResourceMixin` and pass it in
-`ExportJobSerializer` validation
+  `ExportJobSerializer` validation
 
 1.3.1 (2025-01-13)
 ------------------
@@ -21,8 +21,8 @@ UNRELEASED
 * Small actions definition refactor in `ExportJobViewSet/ExportJobViewSet` to allow easier overriding.
 * Add support for ordering in `export`
 * Add settings for DjangoFilterBackend and OrderingFilter in export api.
-`DRF_EXPORT_DJANGO_FILTERS_BACKEND` with default `django_filters.rest_framework.DjangoFilterBackend` and
-`DRF_EXPORT_ORDERING_BACKEND` with default `rest_framework.filters.OrderingFilter`.
+  `DRF_EXPORT_DJANGO_FILTERS_BACKEND` with default `django_filters.rest_framework.DjangoFilterBackend` and
+  `DRF_EXPORT_ORDERING_BACKEND` with default `rest_framework.filters.OrderingFilter`.
 
 1.2.0 (2024-12-26)
 ------------------

docs/getting_started.rst

@@ -135,7 +135,7 @@ a ``status page``, where you can monitor the progress of the import/export proce
    A screenshot of Django Admin export status page
 
 Import/Export API
------------------
+----------------------------------------------------------------
 
 The ``api.views.ExportJobViewSet`` and ``api.views.ImportJobViewSet`` are provided to create
 the corresponding viewsets for the resource.
@@ -172,11 +172,7 @@ the OpenAPI specification will be available.
 
 
 Import/Export API actions mixins
-
-.. figure:: _static/images/action-bands-openapi.png
-
-   A screenshot of the generated OpenAPI specification
------------------
+----------------------------------------------------------------
 
 Alternatively you can use ``api.mixins.ExportStartActionMixin`` and ``api.mixins.ImportStartActionMixin``
 to add to your current viewsets ability to create import/export jobs.
@@ -187,3 +183,7 @@ and ``api.views.BaseImportJobViewSet`` or ``BaseImportJobForUsersViewSet`` to se
 * ``retrieve`` - Returns details of a job based on the provided ID.
 * ``cancel`` - Stops the import/export process and sets the job's status to ``CANCELLED``.
 * ``confirm`` - Confirms the import after the parse stage. This action is available only in import jobs.
+
+.. figure:: _static/images/action-bands-openapi.png
+
+   A screenshot of the generated OpenAPI specification

docs/installation.rst

@@ -81,24 +81,24 @@ By default, it uses the `mimetypes.types_map <https://docs.python.org/3/library/
 from Python's mimetypes module.
 
 ``STATUS_UPDATE_ROW_COUNT``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Defines the number of rows after import/export of which the task status is
 updated. This helps to increase the speed of import/export. The default value
 is 100. This parameter can be specified separately for each resource by adding
 ``status_update_row_count`` to its ``Meta``.
 
 ``DRF_EXPORT_DJANGO_FILTERS_BACKEND``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Specifies filter backend class for ``django-filters`` in export action. Default:
-``django_filters.rest_framework.DjangoFilterBackend``
+Specifies filter backend class for ``django-filters`` in export action.
+Default: ``django_filters.rest_framework.DjangoFilterBackend``
 
 ``DRF_EXPORT_ORDERING_BACKEND``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Specifies filter backend class for ``ordering`` in export action. Default:
-``rest_framework.filters.OrderingFilter``
+Specifies filter backend class for ``ordering`` in export action.
+Default: ``rest_framework.filters.OrderingFilter``
 
 Settings from django-import-export
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/migrate_from_original_import_export.rst

@@ -8,7 +8,7 @@ install the package by following the :ref:`the installation guide<Installation a
 Then, all you need to do is update the base classes for your resource and admin models.
 
 Migrate resources
------------------
+----------------------------------------------------------------
 
 To enable import/export via Celery, simply replace the base resource classes from the original package
 with ``CeleryResource`` or ``CeleryModelResource`` from ``django-import-export-extensions``:

invocations/docs.py

@@ -10,5 +10,7 @@
 def build(context: invoke.Context):
     """Build documentation."""
     saritasa_invocations.print_success("Start building of local documentation")
-    context.run(f"sphinx-build -E -a docs {LOCAL_DOCS_DIR}")
+    context.run(
+        f"sphinx-build -E -a docs {LOCAL_DOCS_DIR} --exception-on-warning",
+    )
     saritasa_invocations.print_success("Building completed")