diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c52efd6..a846257e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,28 +18,43 @@ For questions or anything else you would like to share with the [Project Pythia 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: +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. + +### 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: -``` -conda env create -f ../ci/environment.yml -conda activate pythia -``` + ``` 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): -``` -make html -``` + ``` 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: -``` -open _build/html/index.html -``` + ``` bash + open _build/html/index.html + ``` - When you're done, you can deactivate the dedicated build environment with -``` -conda deactivate -``` + ``` bash + conda deactivate + ``` - You can re-activate the `pythia` conda environment at any time with `conda activate pythia`. diff --git a/content/_static/images/ReadtheDocsAutobuild.png b/content/_static/images/ReadtheDocsAutobuild.png new file mode 100644 index 00000000..25eec582 Binary files /dev/null and b/content/_static/images/ReadtheDocsAutobuild.png differ