chore(docs): Clean up documentation and build script

Our docs have been available in readthedocs.io for a while now, yet we
still have a github workflow pushing docs to a github page. We do care
about docs building properly, but can do without the github page
deployment.

Moreover, the documentation needed some updating in a few sections.

Author: tomasfarias

.github/workflows/docs_pages.yaml

@@ -25,22 +25,12 @@ jobs:
         python-version: ${{ matrix.python-version }}
 
     - name: Install airflow-dbt-python with uv
-      run: uv sync --dev --extra airflow-providers
+      run: uv sync --all-extras --group docs
 
     - name: Install Graphviz
       run: sudo apt-get install graphviz
 
     - name: Build documentation
       run: |
-        mkdir gh-pages
-        touch gh-pages/.nojekyll
         cd docs/
-        uv run sphinx-build -b html . _build
-        cp -r _build/* ../gh-pages/
-
-    - name: Deploy documentation
-      if: ${{ github.ref_type == 'tag' }}
-      uses: JamesIves/github-pages-deploy-action@v4
-      with:
-        branch: gh-pages
-        folder: gh-pages
+        python -m sphinx -T -b dirhtml -d _build/doctrees . html

airflow_dbt_python/hooks/__init__.py

@@ -1 +1 @@
-"""Hooks module provides DbtHooks and DbtFSHooks."""
+"""The hooks module provides Airflow hooks used to interact with dbt."""

airflow_dbt_python/hooks/dbt.py

@@ -1,4 +1,8 @@
-"""Provides a hook to interact with a dbt project."""
+"""Provides a hook to interact with dbt.
+
+Interacting with dbt mainly means setting up a dbt project and running a dbt
+task.
+"""
 
 from __future__ import annotations
 

airflow_dbt_python/hooks/fs/__init__.py

@@ -1,8 +1,7 @@
-"""The DbtFSHook interface includes methods for downloading and uploading files.
+"""A ``DbtFSHook`` can download and upload dbt project files to a filesystem.
 
-Internally, DbtFSHooks can use Airflow hooks to execute the actual operations.
-
-Currently, only AWS S3 and the local filesystem are supported as remotes.
+By filesystem we understand any storage that can hold dbt project files, like an
+S3 bucket or a git repository.
 """
 
 from abc import ABC, abstractmethod

airflow_dbt_python/hooks/target.py

@@ -1,4 +1,9 @@
-"""Provides a hook to get a dbt profile based on the Airflow connection."""
+"""Provides hooks to establish a dbt connection with supported targets.
+
+The connection details will be extracted from an Airflow connection, and each
+target can interpret connection information differently according to its
+specific connection requirements.
+"""
 
 from __future__ import annotations
 

docs/getting_started.rst

@@ -228,7 +228,7 @@ When Airflow is installed is running on a multi- machine or cloud installation,
 
 For these deployments we must rely on a *dbt* remote to download and, eventually, upload all required *dbt* files. The remote *dbt* URL may be used in place of a local ``project_dir`` or ``profiles_dir`` to have *airflow-dbt-python* download the *dbt* files in the remote into a temporary directory for execution.
 
-Interactions with storages are supported by subclasses of ``DbtFSHook``. Read the documentation :ref:`dbt_remote_hooks` to learn more about these hooks.
+Interactions with storages are supported by subclasses of ``DbtFSHook``. Read the documentation :ref:`dbt_fs_hooks` to learn more about these hooks.
 
 As an example, let's upload our *dbt* project to an AWS S3 bucket. The files may end up structured in the bucket as:
 

docs/reference/hooks.rst

@@ -1,41 +1,49 @@
 airflow_dbt_python.hooks
 ========================
 
-Core *dbt* hooks
-----------------
+Core *dbt* hook
+---------------
 
 .. automodule:: airflow_dbt_python.hooks.dbt
    :members:
+   :no-index:
+
+Target hooks
+------------
 
-Supported *dbt* remote hooks
-----------------------------
+.. automodule:: airflow_dbt_python.hooks.target
+   :members:
+   :no-index:
+
+Filesystem hooks
+----------------
 
-The DbtFSHook interface
+The ``DbtFSHook`` interface
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. automodule:: airflow_dbt_python.hooks.remote
+.. automodule:: airflow_dbt_python.hooks.fs.__init__
    :members:
 
-*dbt* git remote
-^^^^^^^^^^^^^^^^
+Git
+^^^
 
-.. automodule:: airflow_dbt_python.hooks.remote.git
+.. automodule:: airflow_dbt_python.hooks.fs.git
    :members:
 
-*dbt* localfs remote
-^^^^^^^^^^^^^^^^^^^^
+Local
+^^^^^
 
-.. automodule:: airflow_dbt_python.hooks.remote.localfs
+.. automodule:: airflow_dbt_python.hooks.fs.local
    :members:
 
-*dbt* S3 remote
-^^^^^^^^^^^^^^^^
+S3
+^^^
 
-.. automodule:: airflow_dbt_python.hooks.remote.s3
+.. automodule:: airflow_dbt_python.hooks.fs.s3
    :members:
 
-*dbt* GCS remote
-^^^^^^^^^^^^^^^^
+GCS
+^^^
 
-.. automodule:: airflow_dbt_python.hooks.remote.gcs
+.. automodule:: airflow_dbt_python.hooks.fs.gcs
    :members: