From 43ae93ee6391476a9ef06964490a638419604579 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 8 Oct 2024 10:17:00 +0100 Subject: [PATCH 01/11] admin docs pages --- docs/source/admin/backup.rst | 4 ++++ docs/source/admin/bulk_updates.rst | 4 ++++ docs/source/admin/django.rst | 4 ++++ docs/source/admin/index.rst | 5 +++++ docs/source/admin/repo_structure.rst | 4 ++++ docs/source/admin/schema.rst | 4 ++++ docs/source/admin/testing.rst | 5 +++++ 7 files changed, 30 insertions(+) create mode 100644 docs/source/admin/backup.rst create mode 100644 docs/source/admin/bulk_updates.rst create mode 100644 docs/source/admin/django.rst create mode 100644 docs/source/admin/repo_structure.rst create mode 100644 docs/source/admin/schema.rst diff --git a/docs/source/admin/backup.rst b/docs/source/admin/backup.rst new file mode 100644 index 000000000..158048897 --- /dev/null +++ b/docs/source/admin/backup.rst @@ -0,0 +1,4 @@ +Database backups +=============== + +... \ No newline at end of file diff --git a/docs/source/admin/bulk_updates.rst b/docs/source/admin/bulk_updates.rst new file mode 100644 index 000000000..eca4b19e1 --- /dev/null +++ b/docs/source/admin/bulk_updates.rst @@ -0,0 +1,4 @@ +Adding new datasets to the Seshat database +======================================== + +... \ No newline at end of file diff --git a/docs/source/admin/django.rst b/docs/source/admin/django.rst new file mode 100644 index 000000000..89c81af1f --- /dev/null +++ b/docs/source/admin/django.rst @@ -0,0 +1,4 @@ +Using Django in Seshat +====================== + +... \ No newline at end of file diff --git a/docs/source/admin/index.rst b/docs/source/admin/index.rst index f953eb43d..6422d2465 100644 --- a/docs/source/admin/index.rst +++ b/docs/source/admin/index.rst @@ -1,6 +1,11 @@ Seshat Databank Admin ============ +Getting started as a Seshat Databank Admin +------------------------------------------ + +*TODO: Add instructions for getting started as a Seshat Databank Admin.* + .. toctree:: :maxdepth: 3 diff --git a/docs/source/admin/repo_structure.rst b/docs/source/admin/repo_structure.rst new file mode 100644 index 000000000..2f74973b0 --- /dev/null +++ b/docs/source/admin/repo_structure.rst @@ -0,0 +1,4 @@ +Seshat Github repo structure +============================ + +... \ No newline at end of file diff --git a/docs/source/admin/schema.rst b/docs/source/admin/schema.rst new file mode 100644 index 000000000..155a6757d --- /dev/null +++ b/docs/source/admin/schema.rst @@ -0,0 +1,4 @@ +Database schema map +=================== + +... \ No newline at end of file diff --git a/docs/source/admin/testing.rst b/docs/source/admin/testing.rst index ff502daf7..58c385c86 100644 --- a/docs/source/admin/testing.rst +++ b/docs/source/admin/testing.rst @@ -40,3 +40,8 @@ To set up pushing the docker image using the GH action workflow, I first did the - Generated a new GitHub token with the ``read:packages`` and ``write:packages`` scopes. Under my ``Settings > Developer settings > Personal access tokens`` (classic token). - Stored the GitHub token as a secret in the Seshat GitHub repository, ``Settings > Secrets``, named ``GH_TOKEN``. + +Adding new tests +---------------- + +*TODO: Add instructions for adding new tests.* From 8b2af95c16c551e5d026598f9f13675b96f31fc8 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 8 Oct 2024 10:26:24 +0100 Subject: [PATCH 02/11] add new pages to index --- docs/source/admin/index.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/source/admin/index.rst b/docs/source/admin/index.rst index 6422d2465..8b75430d8 100644 --- a/docs/source/admin/index.rst +++ b/docs/source/admin/index.rst @@ -9,11 +9,17 @@ Getting started as a Seshat Databank Admin .. toctree:: :maxdepth: 3 - setup/index developers-guide + repo_structure + django + bulk_updates + backup + schema testing api/index websites + setup/index + From 85be31b7b41a3b5a4fc2b39851f8ccf44fb4471c Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 8 Oct 2024 10:34:53 +0100 Subject: [PATCH 03/11] refina admin pages --- docs/source/admin/index.rst | 5 ++--- docs/source/index.rst | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/source/admin/index.rst b/docs/source/admin/index.rst index 8b75430d8..37723c523 100644 --- a/docs/source/admin/index.rst +++ b/docs/source/admin/index.rst @@ -1,10 +1,9 @@ Seshat Databank Admin ============ -Getting started as a Seshat Databank Admin ------------------------------------------- +This section of the documentation is for the Seshat Databank Admins: members of the Seshat team responsible for the maintenance and development of the Seshat codebase, database and website. -*TODO: Add instructions for getting started as a Seshat Databank Admin.* +If you are new to the Seshat project, you should review these pages, in particular the Getting Started section of the Developers Guide. .. toctree:: :maxdepth: 3 diff --git a/docs/source/index.rst b/docs/source/index.rst index 3da1d3a23..22ed81799 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,7 +10,7 @@ On this site you will find documentation for the Seshat project, such as how-to The documentation is divided into sections based on the role of the reader, which match the access level of your account on the Seshat website. These roles are defined as follows: -1. Seshat Databank Admin: A member of the Seshat team responsible for the maintenance and development of the Seshat codebase. +1. Seshat Databank Admin: A member of the Seshat team responsible for the maintenance and development of the Seshat codebase, database and website. 2. Research Assistant: A researcher contributing to 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. Public User: An academic or other interested party who has created an account on the Seshat website to suggest data edits. From 52543c50f0e3b5da94a2316e9bdbb0a5d9103f20 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 8 Oct 2024 11:10:32 +0100 Subject: [PATCH 04/11] RA docs --- docs/source/research_assistant/cliopatria.rst | 4 ++-- docs/source/research_assistant/datasets.rst | 13 +++++++++++++ docs/source/research_assistant/getting_started.rst | 4 ++++ docs/source/research_assistant/index.rst | 4 ++++ docs/source/research_assistant/projects.rst | 4 ++++ docs/source/research_assistant/website.rst | 10 ++++++++++ 6 files changed, 37 insertions(+), 2 deletions(-) create mode 100644 docs/source/research_assistant/datasets.rst create mode 100644 docs/source/research_assistant/getting_started.rst create mode 100644 docs/source/research_assistant/projects.rst create mode 100644 docs/source/research_assistant/website.rst diff --git a/docs/source/research_assistant/cliopatria.rst b/docs/source/research_assistant/cliopatria.rst index 8ee7fcbda..e7269de46 100644 --- a/docs/source/research_assistant/cliopatria.rst +++ b/docs/source/research_assistant/cliopatria.rst @@ -1,5 +1,5 @@ -Cliopatria -========= +How to edit the Cliopatria 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. diff --git a/docs/source/research_assistant/datasets.rst b/docs/source/research_assistant/datasets.rst new file mode 100644 index 000000000..892ced00d --- /dev/null +++ b/docs/source/research_assistant/datasets.rst @@ -0,0 +1,13 @@ +Seshat datasets +=============== + +Data downloads +-------------- + + +Data cleaning code +----------------- + + +Making your dataset available to others +--------------------------------------- \ No newline at end of file diff --git a/docs/source/research_assistant/getting_started.rst b/docs/source/research_assistant/getting_started.rst new file mode 100644 index 000000000..db4b49aad --- /dev/null +++ b/docs/source/research_assistant/getting_started.rst @@ -0,0 +1,4 @@ +Getting started with Seshat data +================================= + +... \ No newline at end of file diff --git a/docs/source/research_assistant/index.rst b/docs/source/research_assistant/index.rst index d1146eddd..f673871bd 100644 --- a/docs/source/research_assistant/index.rst +++ b/docs/source/research_assistant/index.rst @@ -4,7 +4,11 @@ Research Assistant .. toctree:: :maxdepth: 3 + getting_started + datasets cliopatria + projects + website See also the `API documentation <../api/index.rst>`_. diff --git a/docs/source/research_assistant/projects.rst b/docs/source/research_assistant/projects.rst new file mode 100644 index 000000000..8b8f25612 --- /dev/null +++ b/docs/source/research_assistant/projects.rst @@ -0,0 +1,4 @@ +Seshat projects +=============== + +... \ No newline at end of file diff --git a/docs/source/research_assistant/website.rst b/docs/source/research_assistant/website.rst new file mode 100644 index 000000000..d63910216 --- /dev/null +++ b/docs/source/research_assistant/website.rst @@ -0,0 +1,10 @@ +How to use the Seshat website to make and discuss data edits +============================================================= + + +Making and approving data edits +------------------------------- + + +Discussing data edits via private comments +-------------------------------------------- \ No newline at end of file From 97ce9a0584872ef1f1335e46c099a8298e45c4e7 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 8 Oct 2024 11:13:57 +0100 Subject: [PATCH 05/11] rename RA to R --- docs/source/index.rst | 4 ++-- docs/source/{research_assistant => researcher}/cliopatria.rst | 0 docs/source/{research_assistant => researcher}/datasets.rst | 0 .../{research_assistant => researcher}/getting_started.rst | 0 docs/source/{research_assistant => researcher}/index.rst | 2 +- docs/source/{research_assistant => researcher}/projects.rst | 0 docs/source/{research_assistant => researcher}/website.rst | 0 7 files changed, 3 insertions(+), 3 deletions(-) rename docs/source/{research_assistant => researcher}/cliopatria.rst (100%) rename docs/source/{research_assistant => researcher}/datasets.rst (100%) rename docs/source/{research_assistant => researcher}/getting_started.rst (100%) rename docs/source/{research_assistant => researcher}/index.rst (89%) rename docs/source/{research_assistant => researcher}/projects.rst (100%) rename docs/source/{research_assistant => researcher}/website.rst (100%) diff --git a/docs/source/index.rst b/docs/source/index.rst index 22ed81799..6fed99fc3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -11,7 +11,7 @@ On this site you will find documentation for the Seshat project, such as how-to The documentation is divided into sections based on the role of the reader, which match the access level of your account on the Seshat website. These roles 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. Research Assistant: A researcher contributing to the Seshat data as part of an ongoing Seshat affiliated project. +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. Public User: An academic or other interested party who has created an account on the Seshat website to suggest data edits. @@ -19,7 +19,7 @@ The documentation is divided into sections based on the role of the reader, whic :maxdepth: 2 admin/index - research_assistant/index + researcher/index expert/index public_user/index api/index diff --git a/docs/source/research_assistant/cliopatria.rst b/docs/source/researcher/cliopatria.rst similarity index 100% rename from docs/source/research_assistant/cliopatria.rst rename to docs/source/researcher/cliopatria.rst diff --git a/docs/source/research_assistant/datasets.rst b/docs/source/researcher/datasets.rst similarity index 100% rename from docs/source/research_assistant/datasets.rst rename to docs/source/researcher/datasets.rst diff --git a/docs/source/research_assistant/getting_started.rst b/docs/source/researcher/getting_started.rst similarity index 100% rename from docs/source/research_assistant/getting_started.rst rename to docs/source/researcher/getting_started.rst diff --git a/docs/source/research_assistant/index.rst b/docs/source/researcher/index.rst similarity index 89% rename from docs/source/research_assistant/index.rst rename to docs/source/researcher/index.rst index f673871bd..be8c781f8 100644 --- a/docs/source/research_assistant/index.rst +++ b/docs/source/researcher/index.rst @@ -1,4 +1,4 @@ -Research Assistant +Researcher ============ .. toctree:: diff --git a/docs/source/research_assistant/projects.rst b/docs/source/researcher/projects.rst similarity index 100% rename from docs/source/research_assistant/projects.rst rename to docs/source/researcher/projects.rst diff --git a/docs/source/research_assistant/website.rst b/docs/source/researcher/website.rst similarity index 100% rename from docs/source/research_assistant/website.rst rename to docs/source/researcher/website.rst From 9bb2e37a1c041f62cd80a63e24bca72cb0af306e Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 8 Oct 2024 11:34:13 +0100 Subject: [PATCH 06/11] researcher home page --- docs/source/researcher/getting_started.rst | 8 +++++++- docs/source/researcher/index.rst | 4 ++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/source/researcher/getting_started.rst b/docs/source/researcher/getting_started.rst index db4b49aad..32b067e60 100644 --- a/docs/source/researcher/getting_started.rst +++ b/docs/source/researcher/getting_started.rst @@ -1,4 +1,10 @@ Getting started with Seshat data ================================= -... \ No newline at end of file + +Loading Seshat data in Python via the Seshat API +------------------------------------------------ + + +Working with the Cliopatria borders dataset +-------------------------------------------- \ No newline at end of file diff --git a/docs/source/researcher/index.rst b/docs/source/researcher/index.rst index be8c781f8..3e455f96d 100644 --- a/docs/source/researcher/index.rst +++ b/docs/source/researcher/index.rst @@ -1,6 +1,10 @@ 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, which contains example notebooks for loading Seshat data in Python. + .. toctree:: :maxdepth: 3 From 70177133c020081fadd2e11ab241dededf7c6164 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 8 Oct 2024 11:41:53 +0100 Subject: [PATCH 07/11] expert and public user pages --- docs/source/expert/index.rst | 14 +++++++++++++- docs/source/public_user/index.rst | 10 +++++++++- docs/source/researcher/getting_started.rst | 4 ++++ 3 files changed, 26 insertions(+), 2 deletions(-) diff --git a/docs/source/expert/index.rst b/docs/source/expert/index.rst index b7cd86e9d..5a6e7e99d 100644 --- a/docs/source/expert/index.rst +++ b/docs/source/expert/index.rst @@ -1,7 +1,19 @@ Seshat Expert ============ -TODO: Add content here +This page includes help for our Seshat Experts: collaborators with the necessary expertise and permission to approve or reject changes to the Seshat data. + + +Creating a login on the Seshat website +--------------------------------------- + + +Making and approving data edits +------------------------------- + + +Discussing data edits via private comments +-------------------------------------------- diff --git a/docs/source/public_user/index.rst b/docs/source/public_user/index.rst index ef04ae7eb..bec8c1e3f 100644 --- a/docs/source/public_user/index.rst +++ b/docs/source/public_user/index.rst @@ -1,7 +1,15 @@ Public User ============ -TODO: Add content here +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 +--------------------------------------- + + +Suggesting data edits +--------------------- diff --git a/docs/source/researcher/getting_started.rst b/docs/source/researcher/getting_started.rst index 32b067e60..dcfeb710f 100644 --- a/docs/source/researcher/getting_started.rst +++ b/docs/source/researcher/getting_started.rst @@ -2,6 +2,10 @@ Getting started with Seshat data ================================= +Creating a login on the Seshat website +--------------------------------------- + + Loading Seshat data in Python via the Seshat API ------------------------------------------------ From 8cf4f9866c72b2c089146f93b140db9367138333 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 8 Oct 2024 11:51:01 +0100 Subject: [PATCH 08/11] help page --- docs/source/admin/index.rst | 2 ++ docs/source/contact.rst | 4 ---- docs/source/help.rst | 4 ++++ docs/source/index.rst | 2 +- docs/source/researcher/index.rst | 2 ++ 5 files changed, 9 insertions(+), 5 deletions(-) delete mode 100644 docs/source/contact.rst create mode 100644 docs/source/help.rst diff --git a/docs/source/admin/index.rst b/docs/source/admin/index.rst index 37723c523..cda255f3d 100644 --- a/docs/source/admin/index.rst +++ b/docs/source/admin/index.rst @@ -5,6 +5,8 @@ This section of the documentation is for the Seshat Databank Admins: members of If you are new to the Seshat project, you should review these pages, in particular the Getting Started section of the Developers Guide. +You may also wish to review the `help <../help.rst>`_ page to see who on the Seshat team can help you with various tasks. + .. toctree:: :maxdepth: 3 diff --git a/docs/source/contact.rst b/docs/source/contact.rst deleted file mode 100644 index 15c92a53f..000000000 --- a/docs/source/contact.rst +++ /dev/null @@ -1,4 +0,0 @@ -Contact -================================ - -... \ No newline at end of file diff --git a/docs/source/help.rst b/docs/source/help.rst new file mode 100644 index 000000000..1fe82c170 --- /dev/null +++ b/docs/source/help.rst @@ -0,0 +1,4 @@ +Help +==== + +Who can help me if... \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 6fed99fc3..d77733f7c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -24,7 +24,7 @@ The documentation is divided into sections based on the role of the reader, whic public_user/index api/index code-of-conduct - contact + help diff --git a/docs/source/researcher/index.rst b/docs/source/researcher/index.rst index 3e455f96d..a194a2e22 100644 --- a/docs/source/researcher/index.rst +++ b/docs/source/researcher/index.rst @@ -5,6 +5,8 @@ These pages are useful for any researcher contributing to, or consuming, the Ses A great place to start for someone new on the project is the `Getting started with Seshat data `_ page, which contains example notebooks for loading Seshat data in Python. +You may also wish to review the `help <../help.rst>`_ page to see who on the Seshat team can help you with various tasks. + .. toctree:: :maxdepth: 3 From 622bc6a40cd9c987ec0adc66e0ae246919d2932c Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 8 Oct 2024 12:01:25 +0100 Subject: [PATCH 09/11] replace help page with team --- docs/source/admin/index.rst | 2 +- docs/source/help.rst | 4 ---- docs/source/index.rst | 3 ++- docs/source/researcher/index.rst | 2 +- docs/source/team.rst | 14 ++++++++++++++ 5 files changed, 18 insertions(+), 7 deletions(-) delete mode 100644 docs/source/help.rst create mode 100644 docs/source/team.rst diff --git a/docs/source/admin/index.rst b/docs/source/admin/index.rst index cda255f3d..f44227451 100644 --- a/docs/source/admin/index.rst +++ b/docs/source/admin/index.rst @@ -5,7 +5,7 @@ This section of the documentation is for the Seshat Databank Admins: members of If you are new to the Seshat project, you should review these pages, in particular the Getting Started section of the Developers Guide. -You may also wish to review the `help <../help.rst>`_ page to see who on the Seshat team can help you with various tasks. +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. .. toctree:: :maxdepth: 3 diff --git a/docs/source/help.rst b/docs/source/help.rst deleted file mode 100644 index 1fe82c170..000000000 --- a/docs/source/help.rst +++ /dev/null @@ -1,4 +0,0 @@ -Help -==== - -Who can help me if... \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index d77733f7c..288cf974a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -24,7 +24,8 @@ The documentation is divided into sections based on the role of the reader, whic public_user/index api/index code-of-conduct - help + team + resources diff --git a/docs/source/researcher/index.rst b/docs/source/researcher/index.rst index a194a2e22..1f9b88ba5 100644 --- a/docs/source/researcher/index.rst +++ b/docs/source/researcher/index.rst @@ -5,7 +5,7 @@ These pages are useful for any researcher contributing to, or consuming, the Ses A great place to start for someone new on the project is the `Getting started with Seshat data `_ page, which contains example notebooks for loading Seshat data in Python. -You may also wish to review the `help <../help.rst>`_ page to see who on the Seshat team can help you with various tasks. +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. .. toctree:: :maxdepth: 3 diff --git a/docs/source/team.rst b/docs/source/team.rst new file mode 100644 index 000000000..cbe59aeb7 --- /dev/null +++ b/docs/source/team.rst @@ -0,0 +1,14 @@ +Team +==== + + +Contact +------- + + +Who can help me if... +---- + + +Communication channels +---------------------- From 64d02ab72ab7f36388bc7562deba0bcb2b6ca14e Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 8 Oct 2024 12:04:34 +0100 Subject: [PATCH 10/11] resources --- docs/source/index.rst | 5 ++--- docs/source/resources.rst | 26 ++++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 3 deletions(-) create mode 100644 docs/source/resources.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 288cf974a..6b895547e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -22,11 +22,10 @@ The documentation is divided into sections based on the role of the reader, whic researcher/index expert/index public_user/index - api/index - code-of-conduct team resources - + api/index + code-of-conduct Indices and tables diff --git a/docs/source/resources.rst b/docs/source/resources.rst new file mode 100644 index 000000000..ab89c8a5f --- /dev/null +++ b/docs/source/resources.rst @@ -0,0 +1,26 @@ +List of Seshat project resources +=============================== + + +Papers +----- + + +GitHub +------ + + +Zenodo +------ + + +Websites +-------- + + +Codebooks +--------- + + +Shared drives +------------- From 4bb4ff4eb6dbd43b0d2d730a774f4744b15b3682 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 8 Oct 2024 12:04:58 +0100 Subject: [PATCH 11/11] remove indices and tables --- docs/source/index.rst | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 6b895547e..408f47149 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -27,10 +27,3 @@ The documentation is divided into sections based on the role of the reader, whic api/index code-of-conduct - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search`