Merge pull request #121 from alan-turing-institute/pyyaml-install-docs

Pyyaml install docs

.github/workflows/pre-commit.yml

@@ -40,6 +40,13 @@ jobs:
         shell: bash
         if: steps.poetry-cache.outputs.cache-hit != 'true'
         run: |
+          # workaround start
+          # this is a pyyaml v5 vs cython v3 conflict workaround
+          # see https://github.com/alan-turing-institute/sqlsynthgen/issues/120
+          python -m poetry run pip install "cython<3"
+          python -m poetry run pip install wheel
+          python -m poetry run pip install --no-build-isolation "pyyaml==5.4.1"
+          # workaround end
           python -m poetry install --all-extras
       - name: Install Pre-Commit
         shell: bash

.github/workflows/tests.yml

@@ -46,6 +46,13 @@ jobs:
         shell: bash
         if: steps.poetry-cache.outputs.cache-hit != 'true'
         run: |
+          # workaround start
+          # this is a pyyaml v5 vs cython v3 conflict workaround
+          # see https://github.com/alan-turing-institute/sqlsynthgen/issues/120
+          python -m poetry run pip install "cython<3"
+          python -m poetry run pip install wheel
+          python -m poetry run pip install --no-build-isolation "pyyaml==5.4.1"
+          # workaround end
           python -m poetry install --all-extras
       - name: Create src database
         shell: bash

.readthedocs.yaml

@@ -14,6 +14,13 @@ build:
     # nodejs: "19"
     # rust: "1.64"
     # golang: "1.19"
+  jobs:
+    # This pre-install job is a pyyaml v5 vs cython v3 conflict workaround
+    # see https://github.com/alan-turing-institute/sqlsynthgen/issues/120
+    pre_install:
+      - pip install "cython<3"
+      - pip install wheel
+      - pip install --no-build-isolation "pyyaml==5.4.1"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

CONTRIBUTING.md

@@ -25,7 +25,16 @@ Please install the following software on your workstation:
     poetry install --all-extras
     ```
 
-    *If you don't need to [build the project documentation](#building-documentation-locally), run instead just `poetry install`*
+   If Poetry errors when installing PyYaml, you will need to manually specify the Cython version and manually install PyYaml (this is a temporary workaround for a PyYaml v5 conflict with Cython v3, see [here](https://github.com/yaml/pyyaml/issues/601) for full details):
+
+    ```bash
+    poetry run pip install "cython<3"
+    poetry run pip install wheel
+    poetry run pip install --no-build-isolation "pyyaml==5.4.1"
+    poetry install --all-extras
+    ```
+
+    *If you don't need to [build the project documentation](#building-documentation-locally), run instead just `poetry install`.*
 
 1. Install the git hook scripts. They will run whenever you perform a commit:
 

docs/source/installation.rst

@@ -6,13 +6,23 @@ Installation
 End User
 --------
 
-To use sqlsynthgen, first install it:
+To use SqlSynthGen, first install it:
 
 .. code-block:: console
 
    $ pip install sqlsynthgen
 
-and check that you can view the help message with:
+
+If Pip errors when installing PyYaml, you will need to manually specify the Cython version and manually install PyYaml (this is a temporary workaround for a PyYaml v5 conflict with Cython v3, see `here <https://github.com/yaml/pyyaml/issues/601>`_ for full details):
+
+.. code-block:: console
+
+    pip install "cython<3"
+    pip install wheel
+    pip install --no-build-isolation "pyyaml==5.4.1"
+    pip install sqlsynthgen
+
+Check that you can view the help message with:
 
 .. code-block:: console