Add build instructions

CONTRIBUTING.md

@@ -1,5 +1,7 @@
 # Contributor's Guide
 
+## Overview
+
 Project Pythia is an open community, and all contributions are welcome following our [Code of Conduct](code_of_conduct.md).
 
 The source code for the Pythia Portal is [publicly hosted on github](https://github.com/ProjectPythia/projectpythia.github.io).
@@ -9,3 +11,33 @@ Detailed instructions for new users will be posted here in the near future.
 In the mean time, if you have links to some open educational content that you would like to include in the portal,
 feel free to [open an issue on github](https://github.com/ProjectPythia/projectpythia.github.io/issues)
 or contact any member of the [Project Pythia core team](people) directly.
+
+## Instructions for building the portal site
+
+The portal site is built with [Sphinx](https://www.sphinx-doc.org/).
+
+To build and view the site locally (e.g. for testing new content),
+use [conda](https://docs.conda.io/) to set up a build environment with all dependencies:
+
+- Fork the [source repository](https://github.com/ProjectPythia/projectpythia.github.io) on GitHub
+- Make a local clone of the repository on your machine
+- In your favorite terminal, navigate to the `content` directory of the source repository
+- Use [conda](https://docs.conda.io/) to set up a build environment:
+```
+conda env create -f ../ci/environment.yml
+conda activate pythia
+```
+- Build the site locally using Sphinx (which you just installed in the `pythia` environment, along with all necessary dependencies):
+```
+make html
+```
+- The newly rendered site is now available in `content/_build/html/index.html`.
+Open with your web browser, or from the terminal:
+```
+open _build/html/index.html
+```
+- When you're done, you can deactivate the dedicated build environment with
+```
+conda deactivate
+```
+- You can re-activate the `pythia` conda environment at any time with `conda activate pythia`.

README.md

@@ -1,3 +1,25 @@
 # Project Pythia Portal
 
 ![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/NCAR/pythia-portal/deploy-site/main?logo=github&style=for-the-badge)
+
+This is the source repository for the [Project Pythia portal](https://projectpythia.github.io).
+The portal site is built with [sphinx](https://www.sphinx-doc.org/).
+
+To build the site locally (e.g. for testing new content),
+use [conda](https://docs.conda.io/) to set up a build environment with all dependencies.
+
+First, make a local clone of this source repository on your machine.
+Then, from the `content` directory of the source repository, do this:
+```
+conda env create -f ../ci/environment.yml
+conda activate pythia
+```
+
+You can then build the site:
+```
+make html
+```
+and view the built site in your web browser with
+```
+open _build/html/index.html
+```