Merge pull request #121 from Seshat-Global-History-Databank/updating-…

…the-docs

Updating the docs

.github/ISSUE_TEMPLATE/BUG_REPORT.yml

@@ -87,4 +87,4 @@ body:
       options:
         - label: A fix for the bug has been developed on a branch.
         - label: The bug fix branch has been tested in the Staging website.
-        - label: A pull request has been created for the new branch to be merged into the main branch.
+        - label: A pull request has been created for the new branch to be merged into the dev branch.

.github/ISSUE_TEMPLATE/DOCS_IMPROVEMENT.yml

@@ -59,5 +59,4 @@ body:
         Please confirm the following are completed before this issue can be closed.
       options:
         - label: The documentation improvement has been developed on a branch.
-        - label: The new branch has been tested in the Staging website.
-        - label: A pull request has been created for the new branch to be merged into the main branch.
+        - label: A pull request has been created for the new branch to be merged into the dev branch.

.github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml

@@ -50,4 +50,4 @@ body:
       options:
         - label: The feature has been developed on a feature branch.
         - label: The feature branch has been tested in the Staging website.
-        - label: A pull request has been created for the feature branch to be merged into the main branch.
+        - label: A pull request has been created for the feature branch to be merged into the dev branch.

docs/source/how-to-update-these-docs.rst

@@ -0,0 +1,123 @@
+How to update these docs
+========================
+
+This documentation is intended to editable and updated regularly by the Seshat team.
+This includes any researcher, developer/admin, project manager or project lead working on the Seshat Global History Databank.
+If you are on the Seshat project, you can contribute to these docs by following the steps below.
+
+When and why to update these docs
+---------------------------------
+
+The main purpose of these docs are to ensure that the methods and processes of researchers and developers are well documented and easy to follow, which is helpful for both new and existing team members.
+
+You should update these docs if:
+
+- You have particular method, process or way of working that you'd like to share with the team (or be able to repeat yourself in the future).
+- You have noticed that a particular section of the docs is out of date, incorrect or has important details missing.
+
+How to request an update to these docs
+--------------------------------------
+
+If the documentation update you'd like to make is best handled by someone else, such as one of the Seshat Databank Admins, create a new issue on the `Seshat repository <https://github.com/Seshat-Global-History-Databank/seshat/issues/new/choose>`_.
+
+Choose the "Documentation Improvement" issue template and provide as much detail as possible about the update you'd like to make.
+
+Once the issue is created, you may wish to add a specific person under the "Assignees" section, or leave it blank if you're happy for anyone to pick it up.
+
+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 <software-tools>`_ page to get set up.
+
+Once you have these pre-requisites, you can follow the steps below to update the documentation:
+
+1. Fork the `Seshat repository <https://github.com/Seshat-Global-History-Databank/seshat>`_ to your own GitHub account, by clicking the "Fork" button in the top right of the repository page.
+
+    - Note: if you have done this before, go straight to your forked repository and click the "Sync fork" button to ensure you have the latest changes from the original repository.
+
+2. If you haven't already, clone your forked repository to your local machine.
+
+    - Open Terminal (Mac/Linux) or Anaconda Command Prompt (Windows) and navigate to the directory where you want to store the repository.
+
+    - Type the following command to clone the repository, replacing `<your_github_handle>` with your GitHub username:
+
+        .. code-block:: bash
+
+            git clone https://github.com/<your_github_handle>/seshat.git
+
+3. Create a new branch for your changes.
+
+    - Navigate to the repository directory on your local machine and ensure the `dev` branch is up to date.
+
+        .. code-block:: bash
+
+            cd seshat
+            git checkout dev
+            git pull
+    
+    - Create a new branch, with a descriptive name for the changes you are making.
+
+        .. code-block:: bash
+
+            git checkout -b <branch_name>
+
+4. Make your changes to the appropriate documentation page(s) in the `docs/source` directory.
+
+    - The pages are written in "reStructuredText" format. This is a simple markup language that is easy to learn and use. You can find a guide to the syntax `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
+
+    - If adding new pages, ensure they are added to the "toctree" at the top of the `index.rst` file present in the same directory.
+
+5. [Optional] Build the documentation locally to check that your changes are rendering correctly.
+
+    - Install the required dependencies for building the documentation. You may wish to use a virtual environment to avoid conflicts with other Python packages.
+
+        .. code-block:: bash
+
+            conda create -n seshat-docs
+            conda activate seshat-docs
+            pip install -r docs/requirements.txt
+    
+    - Navigate to the `docs` directory and build the HTML version of the documentation.
+
+        .. code-block:: bash
+
+            cd docs
+            make html
+    
+    - Open the `docs/build/html/index.html` file in your browser to view the updated documentation.
+
+6. Use Git to stage and commit your changes.
+
+    - Stage the changes you have made to the repository.
+
+        .. code-block:: bash
+
+            git add docs/source/<path_to_file>
+    
+    - Commit the changes with a descriptive message.
+
+        .. code-block:: bash
+
+            git commit -m "Add/update <page_name> in docs"
+    
+    - Push the changes to your forked repository on GitHub.
+
+        .. code-block:: bash
+
+            git push origin <branch_name>
+
+7. Open a pull request on GitHub.
+
+    - On GitHub, click "Pull requests" and then "New pull request".
+
+    - Set the head repository to your forked repository and the compare branch to the branch you have been working on.
+
+    - Set the base repository to `Seshat-Global-History-Databank/seshat` and the base branch to `dev`.
+
+    - Click "Create pull request" and add a descriptive title and description to the pull request.
+
+    - A Seshat Databank Admin will review your changes and may request further changes before merging the pull request.
+
+    - Once your pull request is merged, the changes will take a few moments before being reflected on this website.

docs/source/index.rst

@@ -4,11 +4,11 @@ Seshat: Global History Databank
 Project Documentation
 ---------------------
 
-The Seshat Global History Databank website can be found at `Seshat DB <https://seshat-db.com/>`_. Seshat has a user login system, with different levels of access depending on the user's role.
+This site includes documentation for the Seshat project, such as how-to guides and technical guidance applicable to those working on, or contributing to Seshat.
 
-On this site you will find documentation for the Seshat project, such as how-to guides and technical guidance applicable to those working on, or contributing to Seshat.
+The purpose is to provide a comprehensive knowledge sharing resource for all aspects of Seshat, including tools for working with the Seshat website and database, as well as reproducible research methods and code.
 
-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:
+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:
 
 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.
@@ -24,6 +24,8 @@ The documentation is divided into sections based on the role of the reader, whic
    public_user/index
    team
    resources
+   software-tools
+   how-to-update-these-docs
    api/index
    code-of-conduct
 

docs/source/researcher/getting_started.rst

@@ -1,6 +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.
 
 Creating a login on the Seshat website
 ---------------------------------------
@@ -9,6 +10,10 @@ Creating a login on the Seshat website
 Loading Seshat data in Python via the Seshat API
 ------------------------------------------------
 
+You may want to start by reading the `Software tools <software-tools>`_ page to ensure you have Python and Git installed on your computer.
+
 
 Working with the Cliopatria borders dataset
---------------------------------------------
+--------------------------------------------
+
+You may want to start by reading the `Software tools <software-tools>`_ page to ensure you have Python and Git installed on your computer.

docs/source/software-tools.rst

@@ -0,0 +1,90 @@
+Software tools
+==============
+
+This section of the documentation provides information on some of the commonly used software tools used in the Seshat project.
+
+If you are participating in a Seshat workshop, run these steps sequentially before the workshop to ensure you have the necessary tools installed on your computer.
+
+Python & Anaconda
+-----------------
+
+.. tabs::
+
+    .. tab:: Mac/Linux
+
+        1. Python is installed on your computer by default.
+        2. Open Terminal and type the following to check the version of Python you have installed:
+
+            .. code-block:: bash
+
+                python --version
+
+            - Note: if you are not familiar with using the command line, you can find Terminal in the Applications folder on your Mac. Pin it to your dock for easy access.
+
+        3. We recommend installing Homebrew, a useful package manager for macOS and Linux.
+
+            - Check if Homebrew is already installed by typing the following in Terminal:
+
+            .. code-block:: bash
+
+                brew --version
+
+            - If not, follow the instructions on the `Homebrew <https://brew.sh/>`_ website to install it.
+
+        4. Install Anaconda via Homebrew by typing:
+
+            .. code-block:: bash
+
+                brew install --cask anaconda
+
+    .. tab:: Windows
+
+        1. Install Anaconda with this `guide <https://docs.anaconda.com/anaconda/install/windows/>`_.
+
+            - Note: to download the installer from the Anaconda website it will ask you to create an account.
+
+        2. Once installed, open the Anaconda command prompt and type the following to check the version of Python you have installed:
+
+            .. code-block:: bash
+
+                python --version
+
+            - Note: you can find the Anaconda command prompt in the Start menu on your Windows computer. Pin it to your taskbar for easy access.
+
+
+Git & GitHub
+------------
+
+.. tabs::
+
+    .. tab:: Mac/Linux
+
+        1. Create an account on `GitHub <https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github>`_.
+
+        2. Check if Git is installed on your computer by opening Terminal and typing:
+
+            .. code-block:: bash
+
+                git --version
+
+        3. If Git is not installed already, install Git via Homebrew by typing:
+
+            .. code-block:: bash
+
+                brew install git
+
+    .. tab:: Windows
+
+        1. Create an account on `GitHub <https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github>`_.
+
+        2. Check if Git is installed on your computer by opening the Anaconda command prompt and typing:
+
+            .. code-block:: bash
+
+                git --version
+
+        3. If Git is not installed already, install Git by typing:
+
+            .. code-block:: bash
+
+                conda install -c conda-forge git