From c058185e5db355e6cdbf022c1dcf0173715c8a18 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 25 Nov 2024 16:41:20 +0000 Subject: [PATCH 01/16] Update documentation roles --- docs/source/index.rst | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 95a3e86a4..2489ef715 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,13 +8,18 @@ The purpose is to provide a comprehensive knowledge sharing resource for all asp Project Roles ------------- -The documentation is divided into sections based on the role of the reader, which match the access level of accounts on the Seshat website. These roles are defined as follows: +The pages of these docs which are most useful will depend on the role of the reader. +These roles, which broadly match the access level of accounts on the Seshat website, are defined as follows: 1. Seshat Databank Admin: A member of the Seshat team responsible for the maintenance and development of the Seshat codebase, database and website. -2. Researcher: Any researcher contributing to, or consuming, the Seshat data as part of an ongoing Seshat affiliated project. -3. Seshat Expert: A collaborator with the necessary expertise and permission to approve or reject changes to the Seshat data. -4. External Seshat Expert: An external collaborator who has the necessary expertise to review and make private comments on Seshat records. -5. Public User: An academic or other interested party who has created an account on the Seshat website to suggest data edits. +2. Researcher: Any researcher contributing to, or consuming, the Seshat data as part of an ongoing Seshat affiliated project, with the necessary expertise and permission to approve or reject changes on the Seshat website. +3. Seshat Expert: An external collaborator who has the necessary expertise to review and make private comments on Seshat records. +4. Public User: An academic or other interested party who has created an account on the Seshat website to suggest data edits. + +Most of the documentation is relevant to **Researchers**, but there is also a section specifically for **Seshat Databank Admins**. + +**Seshat Experts** should review the Getting Started guide. +**Public Users** will not find this documentation particularly useful, beyond the information on how to create an account on the website. Project Documentation --------------------- From 7bc7d9a9417be8b3f3fc6693ced4eee1422dadc8 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 25 Nov 2024 16:53:41 +0000 Subject: [PATCH 02/16] move docs out of researcher folder --- docs/source/{researcher => }/cliopatria.rst | 0 docs/source/{researcher => }/datasets.rst | 0 .../{researcher => }/getting_started.rst | 0 docs/source/index.rst | 6 ++++- .../{researcher/api.rst => python_api.rst} | 0 .../projects.rst => research_code.rst} | 0 docs/source/researcher/index.rst | 22 ------------------- 7 files changed, 5 insertions(+), 23 deletions(-) rename docs/source/{researcher => }/cliopatria.rst (100%) rename docs/source/{researcher => }/datasets.rst (100%) rename docs/source/{researcher => }/getting_started.rst (100%) rename docs/source/{researcher/api.rst => python_api.rst} (100%) rename docs/source/{researcher/projects.rst => research_code.rst} (100%) delete mode 100644 docs/source/researcher/index.rst diff --git a/docs/source/researcher/cliopatria.rst b/docs/source/cliopatria.rst similarity index 100% rename from docs/source/researcher/cliopatria.rst rename to docs/source/cliopatria.rst diff --git a/docs/source/researcher/datasets.rst b/docs/source/datasets.rst similarity index 100% rename from docs/source/researcher/datasets.rst rename to docs/source/datasets.rst diff --git a/docs/source/researcher/getting_started.rst b/docs/source/getting_started.rst similarity index 100% rename from docs/source/researcher/getting_started.rst rename to docs/source/getting_started.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 2489ef715..96533129e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -28,7 +28,11 @@ Project Documentation :maxdepth: 2 admin/index - researcher/index + getting_started + python_api + cliopatria + datasets + research_code expert/index public_user/index team diff --git a/docs/source/researcher/api.rst b/docs/source/python_api.rst similarity index 100% rename from docs/source/researcher/api.rst rename to docs/source/python_api.rst diff --git a/docs/source/researcher/projects.rst b/docs/source/research_code.rst similarity index 100% rename from docs/source/researcher/projects.rst rename to docs/source/research_code.rst diff --git a/docs/source/researcher/index.rst b/docs/source/researcher/index.rst deleted file mode 100644 index 2bbed1c62..000000000 --- a/docs/source/researcher/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -Researcher -============ - -These pages are useful for any researcher contributing to, or consuming, the Seshat data as part of an ongoing Seshat affiliated project. - -A great place to start for someone new on the project is the `Getting started with Seshat data `_ page. - -You may also wish to review the `team <../team.rst>`_ page, which includes a help section, to see who on the Seshat team can help you with various tasks, as well as the `Project resources: where to find them <../resources.rst>`_ page. - -.. toctree:: - :maxdepth: 3 - - getting_started - api - cliopatria - datasets - projects - -See also the `API documentation <../api/index.rst>`_. - - - From 84e6285db303cda986ef708ebf16e0f17ed9f79b Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 25 Nov 2024 16:54:41 +0000 Subject: [PATCH 03/16] remove expert and public user sections --- docs/source/expert/index.rst | 24 ------------------------ docs/source/index.rst | 2 -- docs/source/public_user/index.rst | 18 ------------------ 3 files changed, 44 deletions(-) delete mode 100644 docs/source/expert/index.rst delete mode 100644 docs/source/public_user/index.rst diff --git a/docs/source/expert/index.rst b/docs/source/expert/index.rst deleted file mode 100644 index cab9d637e..000000000 --- a/docs/source/expert/index.rst +++ /dev/null @@ -1,24 +0,0 @@ -Seshat Expert -============ - -This page includes help for our Seshat Experts: collaborators with the necessary expertise and permission to approve or reject changes to the Seshat data. - -A list of experts is maintained on `our project info site `_. - - -Creating a login on the Seshat website ---------------------------------------- - -Creating an account on the Seshat website is the first step to accessing the Seshat data. You can do this by visiting the `Seshat website `_ and clicking the "Sign up" button in the top right corner. - -Follow the information on the screen to create your account. - -Making and approving data edits -------------------------------- - - -Discussing data edits via private comments --------------------------------------------- - - - diff --git a/docs/source/index.rst b/docs/source/index.rst index 96533129e..dbe7cf09b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -33,8 +33,6 @@ Project Documentation cliopatria datasets research_code - expert/index - public_user/index team FAQs resources diff --git a/docs/source/public_user/index.rst b/docs/source/public_user/index.rst deleted file mode 100644 index 937f71375..000000000 --- a/docs/source/public_user/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -Public User -============ - -This page includes help for Seshat Public Users: academics or other interested parties who wish to suggest data edits. - - -Creating a login on the Seshat website ---------------------------------------- - -Creating an account on the Seshat website is the first step to accessing the Seshat data. You can do this by visiting the `Seshat website `_ and clicking the "Sign up" button in the top right corner. - -Follow the information on the screen to create your account. - -Suggesting data edits ---------------------- - - - From 8b51767372577d1bb381227d1fcd6b85833c508b Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 25 Nov 2024 16:55:10 +0000 Subject: [PATCH 04/16] move seshat admin section down --- docs/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index dbe7cf09b..2cb5a2526 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -27,7 +27,6 @@ Project Documentation .. toctree:: :maxdepth: 2 - admin/index getting_started python_api cliopatria @@ -38,6 +37,7 @@ Project Documentation resources software-tools how-to-update-these-docs + admin/index api/index code-of-conduct From e234711152c9b6f7cb42dcd115adbf220f7f9c47 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 25 Nov 2024 17:00:58 +0000 Subject: [PATCH 05/16] simplify --- docs/source/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 2cb5a2526..19df81172 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,8 +18,8 @@ These roles, which broadly match the access level of accounts on the Seshat webs Most of the documentation is relevant to **Researchers**, but there is also a section specifically for **Seshat Databank Admins**. -**Seshat Experts** should review the Getting Started guide. -**Public Users** will not find this documentation particularly useful, beyond the information on how to create an account on the website. +**Seshat Experts** should review `Getting Started with Seshat data `_. +**Public Users** will not find this documentation particularly useful, beyond `Creating a login on the Seshat website `_. Project Documentation --------------------- From 95e3078f226a29137509922338ccca9c18c4b694 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 25 Nov 2024 17:01:26 +0000 Subject: [PATCH 06/16] correcttion --- docs/source/getting_started.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 51e8bec48..77c1cce7e 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -1,7 +1,7 @@ Getting started with Seshat data ================================= -This section of the documentation provides information on how to get started with accessing Seshat data as a researcher, both through the Seshat website and the Seshat API, as well as the Cliopatria borders GeoJSON dataset. +This section of the documentation provides information on how to get started with accessing Seshat data as a researcher, both through the Seshat website and the Seshat API. Creating a login on the Seshat website --------------------------------------- From aa3bcdaeb45b6ed900637cfe2cfa782a91f65523 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 25 Nov 2024 17:03:49 +0000 Subject: [PATCH 07/16] update img links --- docs/source/cliopatria.rst | 4 ++-- docs/source/getting_started.rst | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/source/cliopatria.rst b/docs/source/cliopatria.rst index 5d224ef05..72237a162 100644 --- a/docs/source/cliopatria.rst +++ b/docs/source/cliopatria.rst @@ -38,12 +38,12 @@ To request a specific edit to the Cliopatria dataset, such as changing the shape 1. Click the "Edit" button on the polity page of interest. - .. image:: ../img/edit_cliopatria.png + .. image:: img/edit_cliopatria.png :alt: Edit Cliopatria 2. Fill out the edit page that opens and use the Private Comment box to explain in detail the change you would like. Note the ID of the shape you would like to change. If the change you are requesting is to multiple shapes, please list all the IDs. Click the "Submit for Review" button. - .. image:: ../img/edit_cliopatria_part_2.png + .. image:: img/edit_cliopatria_part_2.png :alt: Edit Cliopatria form 3. This should open a private comment thread where you can discuss the edit with other researchers. See the `Discussing data edits via private comments `_ section for more information. Assign the comment to the person who is best placed to review the edit, e.g. someone who works on Cliopatria (see the `team <../team.rst>`_ page for more information). diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 77c1cce7e..a3ec889b8 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -27,12 +27,12 @@ Once you have created an account and been given the correct permissions, you can - Editing polity info: - .. image:: ../img/edit_polity.png + .. image:: img/edit_polity.png :alt: Edit Polity - Editing a variable: - .. image:: ../img/edit_var.png + .. image:: img/edit_var.png :alt: Edit Variable 2. Fill out the edit page that opens and submit for review. @@ -52,24 +52,24 @@ To create a new private comment: 1. Navigate to a polity page and click the "Add a Private Comment" button. - .. image:: ../img/private_comment.png + .. image:: img/private_comment.png :alt: Private comment button 2. Write your comment and assign someone to look at it, if needed, then click the insert button. - .. image:: ../img/comments.png + .. image:: img/comments.png :alt: Private comment submission If someone has assigned a comment to you: 1. You will see a notification in the top right corner of the website. Click this to view all the comments assigned to you. - .. image:: ../img/notifications.png + .. image:: img/notifications.png :alt: Notifications 2. Click on the comment to view it and respond. Once the discussion thread is completed, the comment can be marked as resolved by checking the checkbox next to the comment and then clicking the "Set Done" button. - .. image:: ../img/set_done.png + .. image:: img/set_done.png :alt: Set comment as done From fca681a34da7573817eee94196d30fabb7a76eca Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Thu, 28 Nov 2024 10:10:01 +0000 Subject: [PATCH 08/16] fix link --- docs/source/python_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/python_api.rst b/docs/source/python_api.rst index 936cafe96..f00640a1c 100644 --- a/docs/source/python_api.rst +++ b/docs/source/python_api.rst @@ -12,7 +12,7 @@ The README file in the `examples` folder provides instructions on how to install .. tip:: - You may want to start by reading the `Software tools `_ page to ensure you have Python and Git installed on your computer. + You may want to start by reading the `Software tools `_ page to ensure you have Python and Git installed on your computer. .. note:: From 02516f94c055c90daf56bf4c1d6d4808d8a561bd Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Thu, 28 Nov 2024 10:12:02 +0000 Subject: [PATCH 09/16] fix link --- docs/source/cliopatria.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/cliopatria.rst b/docs/source/cliopatria.rst index 72237a162..2136358ee 100644 --- a/docs/source/cliopatria.rst +++ b/docs/source/cliopatria.rst @@ -11,7 +11,7 @@ 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 `_. 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 `_, in most cases it is faster and more convenient to download the dataset directly from the GitHub repository and work with it locally. +Whilst Cliopatria can be accessed via the `Seshat API `_, 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 `_ 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. From a8a49672587a9b710fa9df0e9d72820ff989cc28 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Thu, 28 Nov 2024 10:12:52 +0000 Subject: [PATCH 10/16] fix link --- docs/source/getting_started.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index a3ec889b8..d7b6aa9b2 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -11,7 +11,7 @@ Creating an account on the Seshat website is the first step to accessing the Ses Follow the information on the screen to create your account. Ensure you are given the correct permissions for your account by contacting the Seshat team. -See the `team <../team.rst>`_ page for more information. +See the `team `_ page for more information. For most researchers on the project, this will involve being given the "Research Assistant" role permissions, which allows you to make and discuss data edits. .. warning:: From abd3acb4ecb208fe3c8576a4d178e0c8fa82d976 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Thu, 28 Nov 2024 10:13:47 +0000 Subject: [PATCH 11/16] fix link --- docs/source/cliopatria.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/cliopatria.rst b/docs/source/cliopatria.rst index 2136358ee..550e37839 100644 --- a/docs/source/cliopatria.rst +++ b/docs/source/cliopatria.rst @@ -46,7 +46,7 @@ To request a specific edit to the Cliopatria dataset, such as changing the shape .. image:: img/edit_cliopatria_part_2.png :alt: Edit Cliopatria form -3. This should open a private comment thread where you can discuss the edit with other researchers. See the `Discussing data edits via private comments `_ section for more information. Assign the comment to the person who is best placed to review the edit, e.g. someone who works on Cliopatria (see the `team <../team.rst>`_ page for more information). +3. This should open a private comment thread where you can discuss the edit with other researchers. See the `Discussing data edits via private comments `_ section for more information. Assign the comment to the person who is best placed to review the edit, e.g. someone who works on Cliopatria (see the `team `_ page for more information). 4. The reviewer will check the edit request and either make it or ask for more information via the comment thread. From 83b77b128f476249e73cc1c63080a1269a22da5b Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Thu, 28 Nov 2024 10:15:06 +0000 Subject: [PATCH 12/16] fix link --- docs/source/getting_started.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index d7b6aa9b2..ddd92fe5f 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -46,7 +46,7 @@ Discussing data edits via private comments In addition to editing the data directly, you can start a "private comment" discussion about a potential data edit, which other researchers can see and comment on. Users that lack sufficent permissions, and people not logged in, will not be able to see these comments. -You can assign a specific person to the comment, if you know their particular expertise is needed. See the `team <../team.rst>`_ page for more information. +You can assign a specific person to the comment, if you know their particular expertise is needed. See the `team `_ page for more information. To create a new private comment: From 21aea602c7816527ec0498fa17f4d61a04be4c9d Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Thu, 28 Nov 2024 10:18:58 +0000 Subject: [PATCH 13/16] fix link --- docs/source/cliopatria.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/cliopatria.rst b/docs/source/cliopatria.rst index 550e37839..cdbd303d2 100644 --- a/docs/source/cliopatria.rst +++ b/docs/source/cliopatria.rst @@ -20,7 +20,7 @@ Follow the README instructions in the `notebooks` folder. .. tip:: - You may want to start by reading the `Software tools `_ page to ensure you have Python and Git installed on your computer. + You may want to start by reading the `Software tools `_ page to ensure you have Python and Git installed on your computer. Requesting edits to the Cliopatria dataset From 1589cde856136ade13ec5d9d06aaf0bbe859e4e6 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Thu, 28 Nov 2024 10:24:59 +0000 Subject: [PATCH 14/16] fix link --- docs/source/resources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/resources.rst b/docs/source/resources.rst index 650b4b532..d379d14b9 100644 --- a/docs/source/resources.rst +++ b/docs/source/resources.rst @@ -38,7 +38,7 @@ There is a second GitHub organisation at `github.com/seshatdb `_ pages. - - For more information on using the Seshat API python package and the Cliopatria dataset, see the `Researcher `_ pages. + - There are also pages on using the `Seshat API python package `_ and the `Cliopatria dataset `_. Data downloads & code From 1741c2310d20c7e27fc3eb8b976e8c8c001f95de Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Thu, 28 Nov 2024 10:27:06 +0000 Subject: [PATCH 15/16] fix link --- docs/source/how-to-update-these-docs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/how-to-update-these-docs.rst b/docs/source/how-to-update-these-docs.rst index 10d951791..c232902d7 100644 --- a/docs/source/how-to-update-these-docs.rst +++ b/docs/source/how-to-update-these-docs.rst @@ -29,7 +29,7 @@ How to update these docs yourself In order to update these documentation pages, first you'll need to ensure you are set up with an account on GitHub and have Git, Python and Anaconda installed on your computer. -If you lack any of these, follow the steps on the `Software tools `_ page to get set up. +If you lack any of these, follow the steps on the `Software tools `_ page to get set up. Once you have these pre-requisites, you can follow the steps below to update the documentation: From 02ea05f7bb8875edb2968e51e82c2a4a74381ffb Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Thu, 28 Nov 2024 10:31:50 +0000 Subject: [PATCH 16/16] restore experts link --- docs/source/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index 19df81172..4b48736cf 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -19,6 +19,7 @@ These roles, which broadly match the access level of accounts on the Seshat webs Most of the documentation is relevant to **Researchers**, but there is also a section specifically for **Seshat Databank Admins**. **Seshat Experts** should review `Getting Started with Seshat data `_. +A list of experts is maintained `here `_. **Public Users** will not find this documentation particularly useful, beyond `Creating a login on the Seshat website `_. Project Documentation