Merge pull request #155 from alan-turing-institute/docs-improvements

Documentation improvements

Author: mhauru

.github/workflows/pre-commit.yml

@@ -44,12 +44,12 @@ jobs:
         shell: bash
         run: |
           python -m pip install pre-commit
-      - name: Cache Pre-Commit Hooks
-        id: pre-commit-cache
-        uses: actions/cache@v3
-        with:
-          path: ${{ env.PRE_COMMIT_HOME }}
-          key: hooks-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}-${{ env.PYTHON_VERSION }}-${{ hashFiles('poetry.lock') }}
+      # - name: Cache Pre-Commit Hooks
+      #   idna: pre-commit-cache
+      #   usnaes: actions/cache@v3
+      #   winath:
+      #     napath: ${{ env.PRE_COMMIT_HOME }}
+      #     nakey: hooks-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}-${{ env.PYTHON_VERSION }}-${{ hashFiles('poetry.lock') }}
       - name: Install Pre-Commit Hooks
         shell: bash
         if: steps.pre-commit-cache.outputs.cache-hit != 'true'

.readthedocs.yaml

@@ -14,6 +14,19 @@ build:
     # nodejs: "19"
     # rust: "1.64"
     # golang: "1.19"
+  jobs:
+    # See https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-poetry
+    post_create_environment:
+      # Install poetry
+      # https://python-poetry.org/docs/#installing-manually
+      - pip install poetry
+      # Tell poetry to not use a virtual environment
+      - poetry config virtualenvs.create false
+    post_install:
+      # Install dependencies with 'docs' dependency group
+      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
+      - poetry install --extras docs
+
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

…s/source/tutorials/airbnb_db_diagram.png docs/source/airbnb_db_diagram.pngdocs/source/tutorials/airbnb_db_diagram.png renamed to docs/source/airbnb_db_diagram.png docs/source/tutorials/airbnb_db_diagram.png renamed to docs/source/airbnb_db_diagram.png

@@ -1,4 +1,4 @@
-The sqlsynthgen Package
+API Reference
 =======================
 
 Submodules

docs/source/sqlsynthgen.rst docs/source/api.rstdocs/source/sqlsynthgen.rst renamed to docs/source/api.rst

@@ -1,5 +1,5 @@
-Configuration
--------------
+Configuration Reference
+=======================
 
 SqlSynthGen is configured using a YAML file, which is passed to several commands with the ``--config`` option.
 Throughout the docs, we will refer to this file as ``config.yaml`` but it can be called anything (the exception being that there will be a naming conflict if you have a vocabulary table called ``config``).

docs/source/changelog.rst

@@ -7,11 +7,13 @@ Glossary
 
    * - Term
      - Definition
-   * - Custom Generator
-     - A user-defined Python function which will provide one or more random column values when called.
-   * - Destination Database
-     - A database where `sqlsynthgen` creates the source database schema and inserts the synthetic data it generates.
-   * - Source Database
-     - A database that `sqlsynthgen` will create a copy of.
+   * - Row generator
+     - A user-defined Python function which will provide one or more random column values for a single table when called.
+   * - Story generator
+     - A user-defined Python generator function that ``yields`` rows, possibly multiple rows for multiple tables.
+   * - Destination database and destination schema
+     - A database and a schema within that database where `sqlsynthgen` creates the synthetic data tables and inserts the synthetic data it generates.
+   * - Source database and source schema
+     - A database and a schema within that database that `sqlsynthgen` will create a copy of and mimic when creating synthetic data.
    * - Vocabulary Table
      - A table that can be copied in its entirety to the destination database.

docs/source/configuration.rst

@@ -1,13 +1,15 @@
-.. sqlsynthgen documentation master file, created by
-   sphinx-quickstart on Fri Jan 13 15:18:50 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. _page-index:
 
-sqlsynthgen's documentation
-=======================================
+sqlsynthgen's Documentation
+---------------------------
 
 **sqlsynthgen** is a package for making copies of relational databases and populating them with random data.
 
+If you are new to sqlsynthgen (SSG for short), we recommend going through the pages of this documentation roughly in order:
+After :ref:`installing <page-installation>` SSG and learning the basic commands that it uses from the :ref:`quick start guide <page-quickstart>`, the :ref:`introductory tutorial <page-introduction>` will walk you through a relatively simple use case in detail.
+You can then look at one of our other two example use cases, one for :ref:`financial data <page-example-loan-data>` and one for :ref:`health data <page-example-health-data>`.
+The latter also goes through some more advanced features of SSG and how to use them, that are relevant beyond health data use cases.
+
 .. note::
 
    This project will be under active development from Jan - Oct 2023
@@ -28,17 +30,17 @@ Contents:
 
    installation
    quickstart
-   tutorials/*
+   introduction
+   loan_data
+   health_data
    configuration
-   sqlsynthgen
+   api
    faq
-   changelog
    glossary
 
 
-Indices and tables
+Indices and Tables
 ------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`

docs/source/glossary.rst

@@ -1,8 +1,8 @@
+.. _page-installation:
+
 Installation
 ============
 
-.. _enduser:
-
 End User
 --------