Tidy initial docs PR

docs/source/getting-started/setup/cloud/pulumi.rst

@@ -42,7 +42,7 @@ The following instructions assume you have the following software installed:
 
         If you need to install Homebrew, you can find instructions on how to do so on `Homebrew's website <https://brew.sh/>`_.
 
-    If you don't have Pulumi installed, you can install it using Homebrew.
+    If you don't have Pulumi installed, follow the `documentation <https://www.pulumi.com/docs/install/>`_ e.g. on a Mac:
 
     .. code-block:: bash
 
@@ -65,81 +65,87 @@ Ensure that you are correctly logged in and that the subscription you will use c
     $ az account set --subscription "<subscription-id>"
 
 
-Step 2: Activate Pulumi environment and install relevant packages
+Step 2: Create a virtual environment for Pulumi
 -----------------------------------------------------------------
 
-.. admonition:: Setting up a Pulumi environment from scratch
-    :class: dropdown
+You can use either Conda or Python's built-in ``venv`` module to create a virtual environment (you could also re-use the environment you set up for Seshat development and install the requirements there).
 
-    We assume here that you'll use our provided Pulumi setup (located in the ``/pulumi`` directory in this repository).
+.. tabs::
 
-    If you're setting up from scratch, you can follow the below steps to set up the Pulumi environment:
+   .. tab:: Conda example
 
-    1. Create a new Python virtual environment:
+      Create the environment:
 
-       .. code-block:: bash
+      .. code-block:: bash
 
-          $ python3 -m venv venv
+         $ conda create --name seshat_pulumi
 
-    2. Activate the virtual environment and install the required packages:
+      Activate the environment:
 
-       .. code-block:: bash
-
-          $ source venv/bin/activate
-          $ pip install -r requirements.txt
+      .. code-block:: bash
 
-    3. Set up a Pulumi stack:
-
-       .. code-block:: bash
+         $ conda activate seshat_pulumi
 
-          $ pulumi new azure-python
+   .. tab:: venv example
 
-.. important::
+      Create the environment:
 
-   In the provided set up in the ``/pulumi`` directory, we have already set up the Pulumi environment and stack for you.
+      .. code-block:: bash
 
-   In the included set up, we:
+         $ python3 -m venv seshat_pulumi
 
-   - Chose a sensible project name: `seshat-dev`
-   - Chose default stack name
-   - Chose ``UKSouth`` location
-   - Made custom edits to the config files for the Seshat app
+      Activate the environment:
+
+      .. code-block:: bash
 
-To activate the provided Pulumi environment and install the required packages, run the following commands:
+         $ source seshat_pulumi/bin/activate
+
+Install the requirements:
 
 .. code-block:: bash
 
-    $ cd pulumi
-    $ source venv/bin/activate
-    $ pip install -r requirements.txt
+    $ pip install -r pulumi/requirements.txt
 
 Step 3: Set up a Pulumi stack
 ------------------------------
 
+We assume here that you'll use our provided Pulumi setup (located in the ``/pulumi`` directory in this repository).
+
 .. admonition:: Setting up a Pulumi stack from scratch
     :class: dropdown
 
     If you're setting up a Pulumi stack from scratch, you can follow the below steps:
 
-    1. Initialize a new Pulumi stack:
+    1. Set up a Pulumi stack for Azure Python:
+
+       .. code-block:: bash
+
+          $ pulumi new azure-python
+
+    2. Initialize a new Pulumi stack:
 
        .. code-block:: bash
 
           $ pulumi stack init <stack-name>
 
-    2. Select the stack:
+    3. Select the stack:
 
        .. code-block:: bash
 
           $ pulumi stack select <stack-name>
 
 .. important::
 
-    In the provided set up in the ``/pulumi`` directory, we have already set up the Pulumi stack for you.
+   In the provided set up in the ``/pulumi`` directory, we have already set up the Pulumi stack for you.
+
+   In the included set up, we:
 
-    In the included set up, we chose the stack name `seshat`.
+   - Chose a sensible project name: `seshat-dev`
+   - Chose the stack name `seshat`
+   - Chose ``UKSouth`` location
+   - Made custom edits to the config files for the Seshat app
 
-To set up the Pulumi stack, run the following command:
+To set up this Pulumi stack, run the following commands:
 
 .. code-block:: bash
 

docs/source/getting-started/setup/local/macos.rst

@@ -239,7 +239,7 @@ Ensure that all Django database migrations have run:
 Step 11: Load the shape data
 ----------------------------
 
-If the shape data tables are not yet populated in your copy of the Seshat core database and you have access to source data, populate one or more of them with the instructions in [spatialdb.rst](../spatialdb.rst).
+If the shape data tables are not yet populated in your copy of the Seshat core database and you have access to source data, populate one or more of them with the instructions `here <../spatialdb.rst>`_.
 
 
 Step 12: Run Django

docs/source/getting-started/setup/local/ubuntu.rst

@@ -2,8 +2,7 @@ Setting up Seshat in a local Ubuntu environment
 ===============================================
 
 .. hint::
-
-   Local setup steps have been tested on an M1 Mac and on an Ubuntu VM running on the Mac. Instructions for setting up an Ubuntu VM on a Mac can be found :doc:`here </getting-started/setup/local/macos-ubuntu.rst>`.
+    Local setup steps have been tested on an M1 Mac and on an Ubuntu VM running on the Mac. Instructions for setting up an Ubuntu VM on a Mac can be found `here <../getting-started/setup/local/macos-ubuntu.rst>`_.
 
 
 Prerequisites
@@ -269,7 +268,7 @@ Ensure that all Django database migrations have run:
 Step 11: Load the shape data
 ----------------------------
 
-If the shape data tables are not yet populated in your copy of the Seshat core database and you have access to source data, populate one or more of them with the instructions in [spatialdb.rst](../spatialdb.rst).
+If the shape data tables are not yet populated in your copy of the Seshat core database and you have access to source data, populate one or more of them with the instructions `here <../spatialdb.rst>`_.
 
 
 Step 12: Run Django

notebooks/README.md

@@ -0,0 +1,21 @@
+# Visualise Cliopatria shape dataset
+
+Cliopatria is the shape dataset used by the Seshat Global History Databank website. It can also be explored in a local Jupyter notebook running on your local machine by following these instructions.
+
+1. Ensure you have a working installation of Python 3 and Conda. If not, [download Anaconda](https://docs.anaconda.com/free/anaconda/install/index.html), which should give you both
+    - Note: you can use a different tool for creating a Python virtual environment than conda (e.g. venv) if you prefer
+
+2. Set up the required virtual environment, install packages into it and create a jupyter kernel.
+    - Conda example:
+        ```
+            conda create --name cliopatria python=3.11
+            conda activate cliopatria
+            pip install -r requirements.txt
+            python -m ipykernel install --user --name=cliopatria --display-name="Python (cliopatria)"
+        ```
+    - Note: This will install Geopandas 0.13.2, but if you [install from source](https://geopandas.org/en/stable/getting_started/install.html#installing-from-source) it's much faster with version 1.0.0 (unreleased on pip as of 18th June 2024)
+
+3. Open the `cliopatria.ipynb` notebook with Jupyter (or another application that can run notebooks such as VSCode).
+    - `jupyter lab` (or `jupyter notebook`)
+    - Note: make sure the notebook Python kernel is using the virtual environment you created (click top right)
+4. Follow the instructions in the notebook.

notebooks/cliopatria.ipynb

@@ -0,0 +1,144 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Cliopatria viewer\n",
+    "\n",
+    "1. To get started, download a copy of the Cliopatria dataset from here: `[INSERT LINK]`\n",
+    "2. Move the downloaded dataset to an appropriate location on your machine and pass in the paths in the code cell below and run\n",
+    "3. Run the subsequent cells of the notebook\n",
+    "4. Play around with both the GeoDataFrame (gdf) and the rendered map\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cliopatria_geojson_path = \"../data/cliopatria_composite_unique_nonsimplified.geojson_06052024/cliopatria_composite_unique_nonsimplified.geojson\"\n",
+    "cliopatria_json_path = \"../data/cliopatria_composite_unique_nonsimplified.geojson_06052024/cliopatria_composite_unique_nonsimplified_name_years.json\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from map_functions import cliopatria_gdf, display_map"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Load the Cliopatria data to a GeoDataFrame including end years for each shape\n",
+    "gdf = cliopatria_gdf(cliopatria_geojson_path, cliopatria_json_path)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Play with the data on the map\n",
+    "\n",
+    "**Notes**\n",
+    "- The slider is a bit buggy, the best way to change year is to enter a year in the box and hit enter. Use minus numbers for BCE.\n",
+    "- The map is also displayed thrice for some reason!\n",
+    "- Initial attempts to implement a play button similar to the website code failed, but that may not be needed here.\n",
+    "- Click the shapes to reveal the polity display names, using the same logic used in the website code - see `map_functions.py`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "a95aced3593446ceb228a171178f978b",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "IntText(value=0, description='Year:')"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "80c96982f4a34628b3026e9f853a6af9",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "IntSlider(value=0, description='Year:', max=2024, min=-3400)"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "44078fdd8e91499bad99d7fd38b76a65",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Output()"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/Users/echalstrey/.pyenv/versions/3.11.4/lib/python3.11/site-packages/geopandas/geodataframe.py:1538: SettingWithCopyWarning: \n",
+      "A value is trying to be set on a copy of a slice from a DataFrame.\n",
+      "Try using .loc[row_indexer,col_indexer] = value instead\n",
+      "\n",
+      "See the caveats in the documentation: https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#returning-a-view-versus-a-copy\n",
+      "  super().__setitem__(key, value)\n"
+     ]
+    }
+   ],
+   "source": [
+    "display_year = 0\n",
+    "display_map(gdf, display_year)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python (cliopatria1)",
+   "language": "python",
+   "name": "cliopatria1"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}