Merge pull request #25 from Living-with-machines/kallewesterling/issue24

Edit docs + add action
Living-with-machines · Jun 7, 2023 · e87e4af · e87e4af
2 parents b705d5c + 13810c8
commit e87e4af
Show file tree

Hide file tree

Showing 16 changed files with 363 additions and 136 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,74 @@
+name: generate-docs
+
+on:
+  push:
+    branches:
+      - v0.1.0
+  pull_request:
+    branches:
+      - v0.1.0
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: [3.9]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v1
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Bootstrap poetry
+        shell: bash
+        run: |
+          python -m ensurepip
+          python -m pip install --upgrade pip
+          python -m pip install poetry
+
+      - name: Configure poetry
+        shell: bash
+        run: |
+          python -m poetry config virtualenvs.in-project true
+
+      # - name: Set up cache
+      #   uses: actions/cache@v2
+      #   id: cache
+      #   with:
+      #     path: .venv
+      #     key: venv-${{ runner.os }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
+
+      # - name: Ensure cache is healthy
+      #   if: steps.cache.outputs.cache-hit == 'true'
+      #   shell: bash
+      #   run: timeout 10s python -m poetry run pip --version || rm -rf .venv
+
+      # no need for `--extras docs` since we have Sphinx included in main here
+      - name: Install dependencies
+        shell: bash
+        run: |
+          python -m poetry install
+
+      - name: Build documentation
+        run: |
+          mkdir gh-pages
+          touch gh-pages/.nojekyll
+          cd docs/
+          poetry run sphinx-build -b html source _build
+          cp -r _build/* ../gh-pages/
+
+      - name: Deploy documentation
+        # if: ${{ github.event_name == 'push' }}
+        uses: JamesIves/github-pages-deploy-action@4.1.4
+        with:
+          branch: gh-pages
+          folder: gh-pages
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 ## Purpose
 The [Zooniverse citizen science platform's Project Builder](https://www.zooniverse.org/lab) allows anyone to create crowdsourced tasks using uploaded or [imported images](https://blogs.bl.uk/digital-scholarship/2022/04/importing-images-into-zooniverse-with-a-iiif-manifest-introducing-an-experimental-feature.html) and other media. However, its flexibility means that the data created can be difficult to process.
 
-Zoonpyter can help process the output files from the Zooniverse citizen science platform, and facilitate data wrangling, compression, and output into JSON and CSV files. The output files can then be more easily used in e.g. Observable visualisations, Excel and other tools.
+Zoonyper can help process the output files from the Zooniverse citizen science platform, and facilitate data wrangling, compression, and output into JSON and CSV files. The output files can then be more easily used in e.g. Observable visualisations, Excel and other tools.
 
 ## Background
 
@@ -60,11 +60,13 @@ $ pip install zoonyper
 ```
 -->
 
-Because this project is in **active development**, you need to install from the repository for the time being. In order to do so, follow [the installation instructions](docs/source/getting-started/install.rst).
+Because this project is in **active development**, you need to install from the repository for the time being. In order to do so, follow [the installation instructions](docs/source/installing.rst).
 
 ## Documentation
 
-The full documentation is currently available with [`sphinx`](https://www.sphinx-doc.org/en/master/) in the [`docs`](docs) directory.
+You can see the public documentation on https://living-with-machines.github.io/zoonyper.
+
+You can contribute to the documentation using [`sphinx`](https://www.sphinx-doc.org/en/master/) to edit and render the [`docs`](docs) directory.
 
 ## Data model
 

diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
diff --git a/docs/source/api/project.rst b/docs/source/api/project.rst
diff --git a/docs/source/api/utils.rst b/docs/source/api/utils.rst
diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst
@@ -1,5 +1,5 @@
 Getting Started
-##################
+===============
 
 .. rubric:: Content
 

diff --git a/docs/source/getting-started/introduction-to-zoonypers-data-structures.rst b/docs/source/getting-started/introduction-to-zoonypers-data-structures.rst
@@ -1,55 +1,65 @@
 Introduction to Zoonyper's Data Structures
-##########################################
+==========================================
 
 DataFrames constructed from the CSV files
-=========================================
+-----------------------------------------
 
-:attr:`Project.classifications <zoonyper.project.Project.classifications>` is the classifications DataFrame, and has all the functionality of a regular :class:`pandas.DataFrame`:
+:attr:`Project.classifications <zoonyper.project.Project.classifications>` is
+the classifications DataFrame, and has all the functionality of a regular
+:class:`pandas.DataFrame`:
 
 .. code-block:: python
 
     project.classifications.head(2)
 
-:attr:`Project.subjects <zoonyper.project.Project.subjects>` is the subjects DataFrame, and has the same :class:`kind of functionality <pandas.DataFrame>`:
+:attr:`Project.subjects <zoonyper.project.Project.subjects>` is the subjects
+DataFrame, and has the same :class:`kind of functionality <pandas.DataFrame>`:
 
 .. code-block:: python
 
     project.subjects.head(2)
 
-:attr:`Project.workflows <zoonyper.project.Project.workflows>` is the :class:`pandas.DataFrame` representing the project's workflows:
+:attr:`Project.workflows <zoonyper.project.Project.workflows>` is the
+:class:`pandas.DataFrame` representing the project's workflows:
 
 .. code-block:: python
 
     project.workflows.head(2)
 
 Shortcuts to Column Summaries
-=============================
+-----------------------------
 
-:attr:`Project.workflow_ids <zoonyper.project.Project.workflow_ids>` is a list all of the project's workflow IDs:
+:attr:`Project.workflow_ids <zoonyper.project.Project.workflow_ids>` is a list
+of all of the project's workflow IDs:
 
 .. code-block:: python
 
     project.workflow_ids
 
-:attr:`Project.inactive_workflow_ids <zoonyper.project.Project.inactive_workflow_ids>` is a list of the project's inactive workflow's IDs:
+:attr:`Project.inactive_workflow_ids <zoonyper.project.Project.inactive_workflow_ids>`
+is a list of the project's inactive workflow's IDs:
 
 .. code-block:: python
 
     project.inactive_workflow_ids
 
-By using :attr:`Project.workflow_ids <zoonyper.project.Project.workflow_ids>` and :attr:`zoonyper.project.Project.inactive_workflow_ids`, we can get the active workflows by using:
+By using :attr:`Project.workflow_ids <zoonyper.project.Project.workflow_ids>`
+and :attr:`zoonyper.project.Project.inactive_workflow_ids`, we can get the
+active workflows by using:
 
 .. code-block:: python
 
     set(project.workflow_ids) - set(project.inactive_workflow_ids)
 
-:attr:`Project.subject_sets <zoonyper.project.Project.subject_sets>` is a list all of the project's subject sets and corresponding subject IDs:
+:attr:`Project.subject_sets <zoonyper.project.Project.subject_sets>` is a list
+all of the project's subject sets and corresponding subject IDs:
 
 .. code-block:: python
 
     project.subject_sets
 
-:attr:`Project.subject_urls <zoonyper.project.Project.subject_urls>` is a list of all of the project's subjects and their corresponding URLs:
+:attr:`Project.subject_urls <zoonyper.project.Project.subject_urls>` is a list
+of all of the project's subjects and their corresponding URLs:
 
 .. code-block:: python
 

diff --git a/docs/source/getting-started/tutorials/counting-annotations.rst b/docs/source/getting-started/tutorials/counting-annotations.rst
@@ -1,7 +1,10 @@
 Counting annotations
-####################
+====================
 
-:meth:`zoonyper.project.Project.classification_counts` is a useful method for retrieving the number of different classifications per subject ID for any given workflow. It takes two arguments, the workflow ID (passed as ``workflow_id``) and the task number (``task_number``) that you want to extract:
+:meth:`zoonyper.project.Project.classification_counts` is a useful method for
+retrieving the number of different classifications per subject ID for any given
+workflow. It takes two arguments, the workflow ID (passed as ``workflow_id``)
+and the task number (``task_number``) that you want to extract:
 
 .. code-block:: python
 
@@ -11,7 +14,8 @@ Counting annotations
 
   The method currently works best with text annotations.
 
-Using ``classification_counts``, we can also easily check for "agreement", say when all annotators have agreed on *one* classification:
+Using ``classification_counts``, we can also easily check for "agreement", say
+when all annotators have agreed on *one* classification:
 
 .. code-block:: python
     :linenos:
@@ -26,7 +30,8 @@ Using ``classification_counts``, we can also easily check for "agreement", say w
 
     print(agreement)
 
-Similarly, we can construct a code block for whenever at least **four annotators** have agreed on one response for a subject:
+Similarly, we can construct a code block for whenever at least **four
+annotators** have agreed on one response for a subject:
 
 .. code-block:: python
     :linenos:

diff --git a/docs/source/getting-started/tutorials/handling-comments.rst b/docs/source/getting-started/tutorials/handling-comments.rst
@@ -1,28 +1,39 @@
 Handling Comments
-#################
+=================
 
-Comments are an important part of ``zoopyper``'s functionality. They allow access to discussions from Zooniverse's Talk functionality, where volunteers contribute comments on the crowdsourced citizen science projects where they can discuss the project's subjects.
+Comments are an important part of ``zoopyper``'s functionality. They allow
+access to discussions from Zooniverse's Talk functionality, where volunteers
+contribute comments on the crowdsourced citizen science projects where they can
+discuss the project's subjects.
 
-This section will show you how to handle comments using the ``zoopyper`` package, including how to get access to all comments, how to get pre-filtered comments, and how to get comments for a specific subject.
+This section will show you how to handle comments using the ``zoopyper``
+package, including how to get access to all comments, how to get pre-filtered
+comments, and how to get comments for a specific subject.
 
 Getting Access to All Comments
-==============================
+------------------------------
 
-To get access to all comments in the project, you can use the ``Project.comments`` property:
+To get access to all comments in the project, you can use the
+``Project.comments`` property:
 
 .. code-block:: python
 
     # Get all comments for the project
     project.comments
 
-This will return a :class:`pandas.DataFrame` containing all the comments for the project.
+This will return a :class:`pandas.DataFrame` containing all the comments for
+the project.
 
 Getting Pre-Filtered Comments
-=============================
+-----------------------------
 
-To get a pre-filtered comments DataFrame, including only non-staff members, you can use the ``Project.get_comments()`` method with the ``include_staff=False`` setting.
+To get a pre-filtered comments DataFrame, including only non-staff members,
+you can use the ``Project.get_comments()`` method with the
+``include_staff=False`` setting.
 
-If you run it before informing the ``Project`` which users count as "staff", you will get a warning. In the example below, we start by letting the ``Project`` know who is a staff member:
+If you run it before informing the ``Project`` which users count as "staff",
+you will get a warning. In the example below, we start by letting the
+``Project`` know who is a staff member:
 
 .. code-block:: python
 
@@ -32,21 +43,27 @@ If you run it before informing the ``Project`` which users count as "staff", you
     # Get pre-filtered comments
     project.get_comments(include_staff=False)
 
-This will return a :class:`pandas.DataFrame` containing only comments from non-staff members.
+This will return a :class:`pandas.DataFrame` containing only comments from
+non-staff members.
 
 Getting Comments for a Specific Subject
-=======================================
+---------------------------------------
 
-To get comments for a specific subject, you can use the ``Project.get_subject_comments()`` method with the subject ID as the argument:
+To get comments for a specific subject, you can use the
+``Project.get_subject_comments()`` method with the subject ID as the argument:
 
 .. code-block:: python
 
     # Get comments for a specific subject
     project.get_subject_comments(73334345)
 
-This will return a :class:`pandas.DataFrame` containing all the comments for the specified subject.
+This will return a :class:`pandas.DataFrame` containing all the comments for
+the specified subject.
 
-Note that, by default, the ``get_subject_comments`` method will always includes comments from contributors marked as "staff" in Zoonyper. You can disable this by informing the ``Project`` instance about which usernames count as staff and then passing the parameter ``include_staff=False`` to the method:
+Note that, by default, the ``get_subject_comments`` method will always includes
+comments from contributors marked as "staff" in Zoonyper. You can disable this
+by informing the ``Project`` instance about which usernames count as staff and
+then passing the parameter ``include_staff=False`` to the method:
 
 .. code-block:: python
 

diff --git a/docs/source/getting-started/tutorials/index.rst b/docs/source/getting-started/tutorials/index.rst
@@ -1,5 +1,5 @@
 Tutorials
-#########
+=========
 
 .. rubric:: Content