diff --git a/docs/source/researcher/cliopatria.rst b/docs/source/cliopatria.rst similarity index 88% rename from docs/source/researcher/cliopatria.rst rename to docs/source/cliopatria.rst index 5d224ef05..cdbd303d2 100644 --- a/docs/source/researcher/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. @@ -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 @@ -38,15 +38,15 @@ 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). +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. 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/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/researcher/getting_started.rst b/docs/source/getting_started.rst similarity index 86% rename from docs/source/researcher/getting_started.rst rename to docs/source/getting_started.rst index 51e8bec48..ddd92fe5f 100644 --- a/docs/source/researcher/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 --------------------------------------- @@ -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:: @@ -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. @@ -46,30 +46,30 @@ 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: 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 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: diff --git a/docs/source/index.rst b/docs/source/index.rst index 95a3e86a4..4b48736cf 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,13 +8,19 @@ 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 `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 --------------------- @@ -22,15 +28,17 @@ Project Documentation .. toctree:: :maxdepth: 2 - admin/index - researcher/index - expert/index - public_user/index + getting_started + python_api + cliopatria + datasets + research_code team FAQs resources software-tools how-to-update-these-docs + admin/index api/index code-of-conduct 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 ---------------------- - - - diff --git a/docs/source/researcher/api.rst b/docs/source/python_api.rst similarity index 94% rename from docs/source/researcher/api.rst rename to docs/source/python_api.rst index 936cafe96..f00640a1c 100644 --- a/docs/source/researcher/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:: 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>`_. - - - 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