Update docs (#6)

* Update docs

README.md

@@ -4,15 +4,23 @@
   <a href="https://github.com/godatadriven/pytest-dbt-core/actions/workflows/workflow.yml"><img alt="build pytest-dbt-core" src="https://github.com/godatadriven/pytest-dbt-core/actions/workflows/workflow.yml/badge.svg"></a>
 </p>
 
-Pytest dbt core is a [pytest](https://docs.pytest.org) plugin for testing
-your [dbt](https://www.getdbt.com/) projects. It is intended to get quicker
-feedback about if your SQL does what you expect through writing unit tests as
-you are used to with pytest.
+Pytest dbt core is a [pytest](https://docs.pytest.org) plugin for testing your
+[dbt](https://www.getdbt.com/) projects. Write unit test for your dbt logic with
+pytest!
 
-# Install
+# :information_desk_person: User documentation
 
-From your shell, execute the following command.
+The user documentation is hosted on
+[read the docs](https://pytest-dbt-core.readthedocs.io/en/latest/).
 
-``` sh
-$ pip install pytest-dbt-core
-```
+# :raising_hand: Contributing guide
+
+The contributing guide is [here](./CONTRIBUTING.md).
+
+# :gift: How to release
+
+The "how to release" guide is [here](./HOWTORELEASE.md).
+
+# :cop: License
+
+The license is given [here](./LICENSE).

docs/source/conf.py

@@ -30,7 +30,6 @@
 extensions = [
     "sphinx.ext.duration",
     "sphinx.ext.doctest",
-    "myst_parser",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/configuration.rst

@@ -0,0 +1,16 @@
+Configuration
+#############
+
+The plugin runs in the context of a dbt project.
+
+Project directory
+************************
+When you run `pytest` from the root of your project, you do **not** need to set
+the project directory. If you want to run `pytest` from another location, you
+point the `---dbt-project-dir`
+`option <https://docs.pytest.org/en/6.2.x/usage.html#getting-help-on-version-option-names-environment-variables>`_
+to the root of your project.
+
+Profiles directory
+**********************
+If you want to change dbt's profiles directory, use the `DBT_PROFILES_DIR` environment `variable <https://docs.getdbt.com/dbt-cli/configure-your-profile/#advanced-customizing-a-profile-directory>`_.

docs/source/dbt_spark.rst

@@ -0,0 +1,63 @@
+dbt-spark
+#########
+
+`dbt-spark` users are recommend to use the Spark connection method when testing.
+Together with the `pytest Spark plugin <https://github.com/malexer/pytest-spark>`_,
+a on-the-fly Spark session removes the need for hosting Spark.
+
+Installation
+************
+
+Install `dbt-spark`, `pytest-dbt-core` and `pytest-spark` via pip with
+
+.. code-block:: bash
+
+   python -m pip install dbt-spark pytest-dbt-core pytest-spark
+
+
+Configuration
+*************
+
+Configure `pytest-spark` via `pytest configuration <https://docs.pytest.org/en/6.2.x/customize.html#configuration>`_.
+
+.. code-block:: cfg
+
+   # setup.cfg
+   [tool:pytest]
+   spark_options =
+       spark.executor.instances: 1
+       spark.sql.catalogImplementation: in-memory
+
+Usage
+*****
+
+Use the `spark_session` fixture to set-up the unit test for your macro:
+
+.. code-block:: python
+
+   from __future__ import annotations
+
+   import pytest
+   from dbt.clients.jinja import MacroGenerator
+   from pyspark.sql import SparkSession
+
+
+   @pytest.mark.parametrize(
+       "macro_generator", ["macro.spark_utils.get_tables"], indirect=True
+   )
+   def test_create_table(
+       spark_session: SparkSession, macro_generator: MacroGenerator
+   ) -> None:
+       expected_table = "default.example"
+       spark_session.sql(f"CREATE TABLE {expected_table} (id int) USING parquet")
+       tables = macro_generator()
+       assert tables == [expected_table]
+
+Test
+****
+
+Run the Pytest via your preferred interface.
+
+.. code-block:: bash
+
+   pytest

docs/source/index.rst

@@ -3,13 +3,55 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to pytest-dbt-core's documentation!
-===========================================
+pytest-dbt-core
+###############
+
+Write unit tests for your dbt logic with `pytest-dbt-core`!
+`pytest-dbt-core` is a `pytest <https://docs.pytest.org>`_ plugin for testing your
+`dbt <https://getdbt.com>`_ projects.
+
+Installation
+************
+
+Install `pytest-dbt-core` via pip with
+
+.. code-block:: bash
+
+   python -m pip install pytest-dbt-core
+
+Usage
+******
+
+Unit test a macro:
+
+.. code-block:: python
+
+   from __future__ import annotations
+
+   import pytest
+   from dbt.clients.jinja import MacroGenerator
+   from pyspark.sql import SparkSession
+
+
+   @pytest.mark.parametrize(
+       "macro_generator", ["macro.spark_utils.get_tables"], indirect=True
+   )
+   def test_create_table(
+       spark_session: SparkSession, macro_generator: MacroGenerator
+   ) -> None:
+       expected_table = "default.example"
+       spark_session.sql(f"CREATE TABLE {expected_table} (id int) USING parquet")
+       tables = macro_generator()
+       assert tables == [expected_table]
+
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   configuration.rst
+   dbt_spark.rst
+   projects.rst
 
 
 Indices and tables

docs/source/projects.rst

@@ -0,0 +1,6 @@
+Projects
+#############
+
+The following projects use the `pytest-dbt-core` plugin:
+
+* `spark-utils <https://github.com/dbt-labs/spark-utils>`_