refactor to separate cliopatria instructions from api

Seshat-Global-History-Databank · Oct 24, 2024 · eafcd71 · eafcd71
1 parent c873832
commit eafcd71
Show file tree

Hide file tree

Showing 4 changed files with 47 additions and 43 deletions.
diff --git a/docs/source/researcher/api.rst b/docs/source/researcher/api.rst
@@ -0,0 +1,23 @@
+.. _API Getting Started:
+
+Loading Seshat data in Python via the Seshat API
+------------------------------------------------
+
+You can access (and download) the latest Seshat data from the website using the Seshat API (Application Programming Interface).
+The advantage of the API is that it allows you to access up-to-date Seshat data *programmatically*, allowing you to work with this data on your computer in a programming language such as Python.
+
+The best way to get started with loading data via the Seshat API is to use our Python package, which is available at `github.com/Seshat-Global-History-Databank/seshat_api <https://github.com/Seshat-Global-History-Databank/seshat_api>`_.
+If using the API for the first time, open the `examples` folder in the repository where you can find Jupyter notebooks that demonstrate how to use the API to load data in Python.
+The README file in the `examples` folder provides instructions on how to install the package and run the examples.
+
+.. tip::
+
+   You may want to start by reading the `Software tools <software-tools>`_ page to ensure you have Python and Git installed on your computer.
+
+
+.. note::
+
+    - The Seshat API is a RESTful API that allows you to query the Seshat database and retrieve data in JSON format.
+    - It is available on the Seshat website at `seshat-db.com/api <https://seshat-db.com/api/>`_. 
+    - Loading the API in your browser will show you the available endpoints and the data that can be retrieved from them.
+    - There is a filter option that allows you to specify the data you want to retrieve from the API.
diff --git a/docs/source/researcher/cliopatria.rst b/docs/source/researcher/cliopatria.rst
@@ -1,8 +1,29 @@
-How to edit the Cliopatria borders dataset
-===========================================
+Cliopatria polity borders dataset
+=================================
 
 Cliopatria is a comprehensive open-source geospatial dataset of worldwide states, political groups, events, and rulers from 3400BCE to 2024CE.
 It is part of the Seshat Global History Databank project.
 Presently it comprises over 1800 political entities sampled at varying timesteps and spatial scales.
+Cliopatria is available as part of the Seshat database and API and is used on the `World Map <https://seshat-db.com/core/world_map>`_ and polity pages of the Seshat website.
+
+Working with the Cliopatria borders dataset
+--------------------------------------------
+
+Cliopatria is available as a stand-alone dataset which is stored and documented at `github.com/Seshat-Global-History-Databank/cliopatria <https://github.com/Seshat-Global-History-Databank/cliopatria>`_.
+The data takes the form of a single GeoJSON file, a format that can be loaded by a wide variety of software for handling geospatial data.
+Whilst Cliopatria can be accessed via the `Seshat API <api.rst>`_, in most cases it is faster and more convenient to download the dataset directly from the GitHub repository and work with it locally.
+
+A great way to get started exploring the Cliopatria dataset is to open it in the Jupyter notebook examples found inside the `github.com/Seshat-Global-History-Databank/cliopatria <https://github.com/Seshat-Global-History-Databank/cliopatria>`_ GitHub repo.
+The `notebooks` folder contains a processing script to add colors to the dataset, alongside a notebook which loads the data in GeoPandas and includes an interactive Folium plot.
+There is also a notebook which loads Cliopatria and plots some stats about the dataset.
+Follow the README instructions in the `notebooks` folder.
+
+.. tip::
+
+    You may want to start by reading the `Software tools <software-tools>`_ page to ensure you have Python and Git installed on your computer.
+
+
+Cliopatria edit and release process
+-----------------------------------
 
 Instructions for downloading, using and making new releases the dataset are available at the `Cliopatria GitHub repository <https://github.com/Seshat-Global-History-Databank/cliopatria>`_.
diff --git a/docs/source/researcher/getting_started.rst b/docs/source/researcher/getting_started.rst
@@ -76,44 +76,3 @@ If someone has assigned a comment to you:
 .. tip::
 
     You can see all the polities with comments on them by visiting the `Polities with Comments <https://seshat-db.com/core/polities_commented/>`_ page.
-
-
-.. _API Getting Started:
-
-Loading Seshat data in Python via the Seshat API
-------------------------------------------------
-
-You can access (and download) the latest Seshat data from the website using the Seshat API (Application Programming Interface).
-The advantage of the API is that it allows you to access up-to-date Seshat data *programmatically*, allowing you to work with this data on your computer in a programming language such as Python.
-
-The best way to get started with loading data via the Seshat API is to use our Python package, which is available at `github.com/Seshat-Global-History-Databank/seshat_api <https://github.com/Seshat-Global-History-Databank/seshat_api>`_.
-If using the API for the first time, open the `examples` folder in the repository where you can find Jupyter notebooks that demonstrate how to use the API to load data in Python.
-The README file in the `examples` folder provides instructions on how to install the package and run the examples.
-
-.. tip::
-
-   You may want to start by reading the `Software tools <software-tools>`_ page to ensure you have Python and Git installed on your computer.
-
-
-.. note::
-
-    - The Seshat API is a RESTful API that allows you to query the Seshat database and retrieve data in JSON format.
-    - It is available on the Seshat website at `seshat-db.com/api <https://seshat-db.com/api/>`_. 
-    - Loading the API in your browser will show you the available endpoints and the data that can be retrieved from them.
-    - There is a filter option that allows you to specify the data you want to retrieve from the API.
-
-Working with the Cliopatria borders dataset
---------------------------------------------
-
-The Cliopatria borders dataset is available as part of the Seshat database and API. It is used on the `World Map <https://seshat-db.com/core/world_map>`_ and polity pages of the Seshat website.
-
-Cliopatria is also available as a stand-alone dataset which is stored and documented at `github.com/Seshat-Global-History-Databank/cliopatria <https://github.com/Seshat-Global-History-Databank/cliopatria>`_.
-The data takes the form of a single GeoJSON file, a format that can be loaded by a wide variety of software for handling geospatial data.
-
-A great way to get started exploring the Cliopatria dataset is to open it in the Jupyter notebook example found inside the `github.com/Seshat-Global-History-Databank/cliopatria <https://github.com/Seshat-Global-History-Databank/cliopatria>`_ GitHub repo.
-The `notebooks` folder contains a processing script to add colors to the dataset, alongside a notebook which loads the data in GeoPandas and includes an interactive Folium plot.
-Follow the README instructions in the `notebooks` folder.
-
-.. tip::
-
-    You may want to start by reading the `Software tools <software-tools>`_ page to ensure you have Python and Git installed on your computer.
diff --git a/docs/source/researcher/index.rst b/docs/source/researcher/index.rst
@@ -11,6 +11,7 @@ You may also wish to review the `team <../team.rst>`_ page, which includes a hel
    :maxdepth: 3
 
    getting_started
+   api
    datasets
    cliopatria
    projects