Contributors guide (#97)

* Revised contributor's guide

* lint errors

* Missed port forward for local testing somehow

* 2nd attempt to fix lint

* linting

* Update content/pages/contributing.md

Co-authored-by: Anderson Banihirwe <axbanihirwe@ualr.edu>

* Make more consistent with Foundations. Add missing steps for pre-commit hooks

* Address review comments

* reviewer comments

* reviewer comments on git commit

Co-authored-by: Anderson Banihirwe <axbanihirwe@ualr.edu>
Co-authored-by: Julia Kent <46687291+jukent@users.noreply.github.com>
Co-authored-by: Brian Rose <brose@albany.edu>

Author: 4 people

.gitignore

@@ -132,7 +132,6 @@ dmypy.json
 _build/
 _thumbnails/
 content/pages/communications.md
-content/pages/contributing.md
 content/pages/code_of_conduct.md
 content/pages/links.md
 content/pages/links/*.md

CONTRIBUTING.md

@@ -1,60 +1,87 @@
-# Contributor's Guide
+# Pythia Portal contributor's guide
 
-## Overview
+This document contains information specific to contributing to the
+Project Pythia Portal. Please first refer to [Pythia Contributor's
+Guide](https://projectpythia.org/pages/contributing.html) for overall
+contribution guidelines (such as detailed description of Project
+Pythia structure, forking, repository cloning, branching, etc.).
 
-Project Pythia is an open community, and all contributions are welcome following our [Code of Conduct](code_of_conduct.md).
+## Instructions for building the portal site
 
-The source code for the Pythia Portal is [publicly hosted on github](https://github.com/ProjectPythia/projectpythia.github.io).
-Contributions to open issues and new Pull Requests are welcome at any time.
-Detailed instructions for new users will be posted here in the near future.
+The portal site is built with [Sphinx](https://www.sphinx-doc.org/).
 
-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.
+When testing new content it is important to build and view the site. Read the Docs automatically builds the site for you when each Pull Request is checked. However, you can also build it locally on your machine following the instructions
+below.
 
-For questions or anything else you would like to share with the [Project Pythia Team](people.md), please reach out to us on our [GitHub Discussions page](https://github.com/ProjectPythia/projectpythia.github.io/discussions).
+### Building the site
 
-## Instructions for building the portal site
+After checking out a local copy of the site, in your favorite terminal, navigate to the `content` directory of the source repository
 
-The portal site is built with [Sphinx](https://www.sphinx-doc.org/).
+```bash
+cd projectpythia.github.io/content
+```
+
+Use [conda](https://docs.conda.io/) to set up a build environment:
+
+```bash
+conda env create -f ../ci/environment.yml
+```
+
+This will create or update the dev environment (`pythia`).
+
+#### Install `pre-commit` hooks
+
+This repository includes `pre-commit` hooks (defined in
+`.pre-commit-config.yaml`). To activate/install these pre-commit
+hooks, run:
+
+```bash
+conda activate pythia
+pre-commit install
+```
+
+Setting up the environment is typically a one-time step.
+
+_NOTE_: The `pre-commit` package is already installed via the `pythia` conda environment.
 
-When testing new content is important to build and view the site. Read the Docs automatically builds the site for you when each Pull Request is checked. You can also build it locally on your machine.
+#### Building the book locally
+
+Build the site locally using Sphinx (which you just installed in the `pythia` environment, along with all necessary dependencies):
+
+```bash
+make html
+```
+
+The newly rendered site is now available in `content/_build/html/index.html`.
+Open with your web browser, or from the terminal:
+
+```bash
+open _build/html/index.html
+```
+
+However, many of the links will not work. For all of the links
+found in the portal to work properly, you'll need to set up a local
+testing server. This can be done with Python's http.server by running
+the following command from within the content directory:
+
+```bash
+python -m http.server --directory _build/html/
+```
+
+and then pointing your browser at the URL: localhost:8000.
+
+More information on setting up a local test server is available from [here](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/set_up_a_local_testing_server)
+
+When you're done, you can deactivate the dedicated build environment with
+
+```bash
+conda deactivate
+```
+
+You can re-activate the `pythia` conda environment at any time with `conda activate pythia`.
 
 ### To view the Read the Docs autobuild
 
 Once a Pull Request has passed all tests, including the Read the Docs build, you can click "Details" of the check that says, "docs/readthedocs.org:projectpythia - Read the Docs build succeeded!" to launch a new tab with a build of the Project Pythia site. (You may have to click "Show all checks" for this to be displayed.)
 
 ![Checks](../_static/images/ReadtheDocsAutobuild.png)
-
-### To build and view the site locally
-
-- Fork the [source repository](https://github.com/ProjectPythia/projectpythia.github.io) on GitHub
-- Make a local clone of the repository on your machine
-  ```bash
-  git clone git@github.com:USERNAME/projectpythia.github.io.git
-  # or
-  git clone https://github.com/USERNAME/projectpythia.github.io.git
-  ```
-- In your favorite terminal, navigate to the `content` directory of the source repository
-  ```bash
-  cd projectpythia.github.io/content
-  ```
-- Use [conda](https://docs.conda.io/) to set up a build environment:
-  ```bash
-  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):
-  ```bash
-  make html
-  ```
-- The newly rendered site is now available in `content/_build/html/index.html`.
-  Open with your web browser, or from the terminal:
-  ```bash
-  open _build/html/index.html
-  ```
-- When you're done, you can deactivate the dedicated build environment with
-  ```bash
-  conda deactivate
-  ```
-- You can re-activate the `pythia` conda environment at any time with `conda activate pythia`.

content/conf.py

@@ -82,7 +82,6 @@
 # Copy root files into content pages -----------------------------------------
 
 shutil.copyfile('../CODEOFCONDUCT.md', 'pages/code_of_conduct.md')
-shutil.copyfile('../CONTRIBUTING.md', 'pages/contributing.md')
 
 # Build Communication Channel Gallery ----------------------------------------