docs: Improve documentation (#66)

* docs: build autodocs * docs: update README and CONTRIBUTING * ci: exclude streamlit files from coverage * ci: actually fix coverage reporting * docs: Update docs build and setup * style: pre-commit fixes * build: Fix comment on api docs build * docs: Update contrib docs headers * chore: update streamlit version and add badges to README * docs: further CONTRIBUTING changes --------- Co-authored-by: Landung 'Don' Setiawan <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
uw-cefs · Jul 31, 2024 · 7d92d7f · 7d92d7f
1 parent f0afa15
commit 7d92d7f
Show file tree

Hide file tree

Showing 27 changed files with 356 additions and 131 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -6,7 +6,11 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
+  jobs:
+    pre_build:
+      # Generate the Sphinx API docs so it builds.
+      - "nox -s build_api_docs"
 sphinx:
   configuration: docs/conf.py
 
@@ -15,4 +19,4 @@ python:
     - method: pip
       path: .
       extra_requirements:
-        - docs
+        - all
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -14,26 +14,44 @@ project.
 
 ### Environment Setup
 
+#### Codespaces Environment Setup
+
+To open a [GitHub Codespace](https://github.com/features/codespaces) where you
+can run and develop the portal, you can click the button below to do so, or by
+following GitHub's guide on how to do so
+[here](https://docs.github.com/en/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository).
+
+It may take a few minutes to get up and running, but once it's ready, you can
+skip ahead to the section **Run Genetic Forensic Portal**.
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/uw-ssec/genetic-forensic-portal?quickstart=1)
+
+This option is especially good for Windows users, as the current scripts to run
+the local Keycloak client are intended for Unix-based operating systems
+(Mac/Linux), and Codespaces can easily provide you with such an environment.
+
+#### Local Environment Setup
+
 Fork the repository, and create your local version, then follow the installation
 steps:
 
 1. Create conda environment
 
-```bash
-conda create -y -n genetic-forensics python=3.12 pip
-```
+   ```bash
+   conda create -y -n genetic-forensics python=3.12 pip
+   ```
 
 2. Activate conda environment
 
-```bash
-conda activate genetic-forensics
-```
+   ```bash
+   conda activate genetic-forensics
+   ```
 
 3. Install dependencies
 
-```bash
-pip install -e ".[dev,docs]"
-```
+   ```bash
+   pip install -e ".[all]"
+   ```
 
 ### Post setup
 
@@ -47,7 +65,7 @@ pre-commit install # Will install a pre-commit hook into the git repo
 NOTE: You can also/alternatively run `pre-commit run` (changes only) or
 `pre-commit run --all-files` to check even without installing the hook.
 
-## Run Genetic Forensic portal
+### Run Genetic Forensic portal
 
 First run the authentication application (Keycloak server) with the following
 command
@@ -62,15 +80,15 @@ You are now ready to run the Genetic Forensic portal Streamlit application:
 gf-portal
 ```
 
-## Stopping the auth portal
+### Stopping the auth portal
 
 To stop the auth portal, run the following command:
 
 ```bash
 gf-auth-stop
 ```
 
-## DO NOT RUN IN PROD: Exporting a list of DEV users from the DEV auth server
+### DO NOT RUN IN PROD: Exporting a list of DEV users from the DEV auth server
 
 To update the Keycloak realm containing the dev users, you can run the following
 command. Do not export your actual production users this way, as you do NOT want
@@ -96,6 +114,47 @@ Unit tests with coverage:
 pytest --cov=genetic_forensic_portal tests/ --cov-report xml:coverage.xml
 ```
 
+## Developing with nox
+
+The fastest way to start with development is to use nox, which will be installed
+as part of the `dev` environment that you have already set up.
+
+To use, run `nox`. This will lint and test using every installed version of
+Python on your system, skipping ones that are not installed. You can also run
+specific jobs:
+
+```console
+$ nox -s lint  # Lint only
+$ nox -s tests  # Python tests
+$ nox -s build_api_docs # Build the API docs from docstrings
+$ nox -s docs -- --serve  # Build and serve the docs
+$ nox -s build  # Make an SDist and wheel
+```
+
+Nox handles everything for you, including setting up an temporary virtual
+environment for each run.
+
+## Building docs
+
+Build the API docs using the command below. This will generate the API
+documentation, which are retrieved from the docstrings in the code.:
+
+```bash
+nox -s build_api_docs
+```
+
+You can see a preview with:
+
+```bash
+nox -s docs -- --serve
+```
+
+You can build the docs to html using:
+
+```bash
+nox -s docs
+```
+
 ## Pull Requests
 
 Please follow the below guidelines when you want to raise a Pull Request:

diff --git a/README.md b/README.md
@@ -1,23 +1,48 @@
-# genetic-forensic-portal
+# Genetic Forensic Portal
+
+[![ssec](https://img.shields.io/badge/SSEC-Project-purple?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA0AAAAOCAQAAABedl5ZAAAACXBIWXMAAAHKAAABygHMtnUxAAAAGXRFWHRTb2Z0d2FyZQB3d3cuaW5rc2NhcGUub3Jnm+48GgAAAMNJREFUGBltwcEqwwEcAOAfc1F2sNsOTqSlNUopSv5jW1YzHHYY/6YtLa1Jy4mbl3Bz8QIeyKM4fMaUxr4vZnEpjWnmLMSYCysxTcddhF25+EvJia5hhCudULAePyRalvUteXIfBgYxJufRuaKuprKsbDjVUrUj40FNQ11PTzEmrCmrevPhRcVQai8m1PRVvOPZgX2JttWYsGhD3atbHWcyUqX4oqDtJkJiJHUYv+R1JbaNHJmP/+Q1HLu2GbNoSm3Ft0+Y1YMdPSTSwQAAAABJRU5ErkJggg==&style=plastic)](https://escience.washington.edu/software-engineering/ssec/)
+[![BSD License](https://badgen.net/badge/license/BSD-3-Clause/blue)](LICENSE)
 
 [![Actions Status][actions-badge]][actions-link]
 [![Documentation Status][rtd-badge]][rtd-link]
 
-[![PyPI version][pypi-version]][pypi-link]
-[![Conda-Forge][conda-badge]][conda-link]
-[![PyPI platforms][pypi-platforms]][pypi-link]
-
 [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/uw-ssec/genetic-forensic-portal/main.svg)](https://results.pre-commit.ci/latest/github/uw-ssec/genetic-forensic-portal/main)
 
 [![GitHub Discussion][github-discussions-badge]][github-discussions-link]
 
+Poaching remains a critical threat to biodiversity worldwide, driving numerous
+species to the brink of extinction. University of Washington’s
+[Center for Environmental Forensic Science (CEFS)](https://cefs.uw.edu/) has a
+history of pioneering forensic techniques to tackle this crisis. Among its
+notable contributions are advancements in genetic forensics, which have
+revolutionized the field of wildlife crime investigation.
+
+Central to CEFS’s approach is the application of genetic analysis to identify
+and track illicit wildlife products. By extracting DNA from confiscated
+specimens, researchers can determine the species, origin, and in certain cases,
+individual identity of the animals involved. This innovative technique has
+proven instrumental in linking poached products to their source populations and
+facilitating law enforcement efforts.
+
+Building upon CEFS’s tradition of innovation, SSEC is developing a secure online
+portal which will enable national labs in Africa and SE Asia to submit genotypes
+acquired from seized ivory for rapid analysis. This collaborative effort brings
+together expertise in software engineering and wildlife forensics to create a
+powerful tool which allows for the uploading, analysis, and visualization of
+genetic data from poached specimens.
+
+[More project details can be found here](https://escience.washington.edu/genetic-forensics-streamlining-poaching-investigations/)
+
+# Running and developing the portal
+
+Instructions to run and contribute to the portal can be found in
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
 <!-- SPHINX-START -->
 
 <!-- prettier-ignore-start -->
 [actions-badge]:            https://github.com/uw-ssec/genetic-forensic-portal/workflows/CI/badge.svg
 [actions-link]:             https://github.com/uw-ssec/genetic-forensic-portal/actions
-[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/genetic-forensic-portal
-[conda-link]:               https://github.com/conda-forge/genetic-forensic-portal-feedstock
 [github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
 [github-discussions-link]:  https://github.com/uw-ssec/genetic-forensic-portal/discussions
 [rtd-badge]:                https://readthedocs.org/projects/genetic-forensic-portal/badge/?version=latest

diff --git a/codecov.yml b/codecov.yml
@@ -1,3 +1,9 @@
 ignore:
+  # Ignore CLI files
   - "src/genetic_forensic_portal/auth.py"
   - "src/genetic_forensic_portal/cli.py"
+  # Ignore streamlit files
+  - "src/genetic_forensic_portal/app/common/setup.py"
+  - "src/genetic_forensic_portal/app/common/download_buttons.py"
+  - "src/genetic_forensic_portal/app/Home.py"
+  - "src/genetic_forensic_portal/app/pages/*"
diff --git a/docs/index.md b/docs/index.md
@@ -3,6 +3,10 @@
 ```{toctree}
 :maxdepth: 2
 :hidden:
+:caption: API
+
+api/genetic_forensic_portal
+test-users
 
 ```
 

diff --git a/noxfile.py b/noxfile.py
@@ -99,7 +99,7 @@ def build_api_docs(session: nox.Session) -> None:
         "--module-first",
         "--no-toc",
         "--force",
-        "../src/genetic_forensic_portal",
+        "../src/genetic_forensic_portal/",
     )
 
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -28,7 +28,7 @@ classifiers = [
 ]
 dynamic = ["version"]
 dependencies = [
-  "streamlit>=1.36,<2",
+  "streamlit>=1.37,<2",
   "pandas>=2.2,<3",
   "python-keycloak>=4.1,<5",
 ]
@@ -41,6 +41,8 @@ gf-auth-dev-export-DO-NOT-RUN-IN-PROD = "genetic_forensic_portal.auth:export"
 
 [project.optional-dependencies]
 dev = [
+  "nox",
+  "pre-commit",
   "pytest >=6",
   "pytest-cov >=3",
   "pytest-mock",
@@ -88,7 +90,14 @@ testpaths = [
 [tool.coverage]
 run.source = ["genetic_forensic_portal"]
 run.omit = [
+  # Omit CLI files
   "src/genetic_forensic_portal/auth.py",
+  "src/genetic_forensic_portal/cli.py",
+  # Omit Streamlit files
+  "src/genetic_forensic_portal/app/common/setup.py",
+  "src/genetic_forensic_portal/app/common/download_buttons.py",
+  "src/genetic_forensic_portal/app/Home.py",
+  "src/genetic_forensic_portal/app/pages/*",
 ]
 report.exclude_also = [
   '\.\.\.',

diff --git a/src/genetic_forensic_portal/app/__init__.py b/src/genetic_forensic_portal/app/__init__.py
diff --git a/src/genetic_forensic_portal/app/client/__init__.py b/src/genetic_forensic_portal/app/client/__init__.py
@@ -0,0 +1,10 @@
+"""This package contains clients that retrieve data and authentication/authorization information for the genetic forensic portal.
+
+Right now, of course, these clients are largely simulating these interactions, but the idea is that they would be able to interact with the actual services once they exist.
+
+If the portal needs to call other services in the future, they would be added here.
+
+Current clients:
+- `gf_api_client`: A client that interacts with the genetic forensic API (but since one does not currently exist, it simulates these interactions but provides canned data).
+- `keycloak_client`: A client that interacts with a local Keycloak instance to make auth decisions.
+"""