Add conda install/setup instructions

docs/contributing.md

@@ -28,7 +28,7 @@ To serve the documentation during local development, run `mkdocs serve` from the
 Documentation is written as a series of markdown files nested by topic in directories.
 
 - All directories at the top-level inside `docs` will represent `navbar` sections.
-  - Each top-level directory should contain an `index.md` file with an overall description of what that section contains.
+  - Each top-level directory should contain an `index.md` file with an overview of what that section contains.
   - The `index.md` should have an L1 header with the same title as the `navbar` section.
   - Markdown files in each directory represent sections shown along the left sidebar.
 - Nested directories within each `navbar` section should be used to add an sections along the left sidebar.

docs/technical-setup/environment-setup/index.md

@@ -0,0 +1,3 @@
+# Environment setup
+
+_Stub for environment setup index page._

docs/technical-setup/environment-setup/setup-conda.md

@@ -0,0 +1,94 @@
+# Install and set up conda
+
+## What is conda?
+
+The OpenScPCA project uses [conda](https://docs.anaconda.com/free/miniconda/index.html) to set up your software environment.
+conda is a command-line software management tool which helps you install and track specific versions of software.
+It also allows you to have multiple software environments with different sets of packages on the same computer.
+
+This page provides instructions on how to install conda and use it to install certain software you will need to contribute to OpenScPCA.
+
+
+### Why use conda?
+
+There are two main reasons we use conda for OpenScPCA:
+
+- conda provides a "one stop shop" for installing lots of different software
+    - Rather than having to figure out how to install every new program and its dependencies, conda can handle it all for you.
+    - You'll use conda to install the software dependencies you'll need to contribute to OpenScPCA.
+- conda allows you set up different software environments for different projects
+    - For example, you may have two projects that require different versions of the same package.
+    With conda, you can create separate, fully isolated software environments for each project with different package versions.
+    - Python-based OpenScPCA analysis modules will use different conda environments to prevent conflicts and improve reproducibility.
+    Therefore, installing conda is also part of setting up your computer to be able to contribute to Python-based modules.
+
+
+## Install conda
+
+We recommend installing [Miniconda](https://docs.anaconda.com/free/miniconda/index.html) to obtain conda.
+Miniconda is lightweight version of the full conda platform and includes the conda tool itself, Python, and a few other commonly-used packages.
+
+To install Miniconda, [download the installer for your operating system](https://docs.anaconda.com/free/miniconda/), and follow all instructions.
+
+  - If you are on a macOS computer, be sure to download one of the links ending in `pkg`, _not `bash`_:
+    - If you are on an Apple Silicon (M1-3) mac, download `Miniconda3 macOS Apple M1 64-bit pkg`
+    - If you are on an Intel mac, download `Miniconda3 macOS Intel x86 64-bit pkg`
+
+If you already have conda on your system, you do not need to re-install it.
+
+## Set up conda
+
+Next, you will need to set certain conda settings and install a few packages that will allow you to contribute to OpenScPCA in general.
+
+1. Open a terminal (command line prompt) to interact with conda.
+
+    ??? info "New to the terminal?"
+
+        If you are new to the terminal, we recommend you start with a general introduction.
+        Here are a few we resources we suggest:
+
+        - macOS
+            - [How to Use Terminal on a Mac: A Beginner's Guide](https://www.makeuseof.com/tag/beginners-guide-mac-terminal/)
+            - [Video: Using the Terminal on macOS for beginners](https://www.youtube.com/watch?v=dWFMRp6KtlQ)
+        - Windows
+            - PENDING: [Getting Started with Powershell](https://learn.microsoft.com/en-us/powershell/scripting/learn/ps101/01-getting-started?view=powershell-7.4)
+
+
+1. Copy and paste the following code into the terminal, and hit enter.
+These commands will set the [recommended channels](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/channels.html) conda should use to search for software.
+    - If you get the error `conda: command not found`, you may need to try again in a new terminal window.
+    If this doesn't help, you can [get help here](STUB_LINK somewhere to get help).
+
+    ```sh
+    conda config --add channels defaults
+    conda config --add channels bioconda
+    conda config --add channels conda-forge
+    conda config --set channel_priority strict
+    ```
+
+
+1. The last step is to install the packages that you will need to contribute to OpenScPCA into your `base` conda environment.
+`base` is the default conda environment, the one that will be active when you first open your terminal.
+Copy and paste the following command into the terminal, and hit enter.
+
+    ```sh
+    conda install awscli jq pre-commit
+    ```
+
+    - The [`awscli` package](https://pypi.org/project/awscli/) will allow you to interact with [data stored in the Amazon Web Services (AWS) S3 bucket](STUB_LINK)
+    - The [`jq` package](https://pypi.org/project/jq/) provides JSON parsing capabilities
+    - The [`pre-commit`](https://pypi.org/project/pre-commit/) package will allow you to use [pre-commit hooks when contributing to analysis modules](STUB_LINK)
+
+    !!! note
+        You may be prompted to enter **`y`** or **`n`** (yes or no) during this setup.
+        If/when this prompt appears, you should hit **`y`** to give conda permissions to proceed.
+
+
+1. At the end of the installation, you should see these messages in the terminal which indicate successful installation:
+
+    <figure markdown="span">
+        ![Conda completed install output.](../../img/conda-success.png){width="275"}
+    </figure>
+
+
+All set! 🎉

mkdocs.yml

@@ -24,6 +24,14 @@ markdown_extensions:
   - admonition  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#admonition
   - attr_list   # https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown.md#attribute-lists
   - md_in_html  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#markdown-in-html
+  - pymdownx.highlight:  # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#configuration
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.details     # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#details
 
 
 # Here is the basic structure of our navigation setup.
@@ -33,6 +41,7 @@ markdown_extensions:
 #    - section-path/markdown-1.md <!-- left sidebar will display H1 title from the markdown file itself -->
 #    - section-path/markdown-2.md
 #    - Subsection name: <!-- This title appears as bold item in left sidebar -->
+#      - section-path/subsection-path/index.md <!-- summary page for this subsection -->
 #      - section-path/subsection-path/markdown-3.md
 
 # Currently, we have templated out the follow navbar items (specific names TBD)
@@ -44,6 +53,9 @@ nav:
     - technical-setup/install-a-github-client.md
     - technical-setup/fork-the-repo.md
     - technical-setup/clone-the-repo.md
+    - Environment setup:
+      - technical-setup/environment-setup/index.md
+      - technical-setup/environment-setup/setup-conda.md
   - Tools for communication:   # Slack, issues, discussions
     - communications-tools/tools-for-communication.md
   - Contributing to analyses:  # Setting up an analysis, all the git stuff