Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Read the Docs autobuild to contributors guide #26

Merged
merged 10 commits into from
Jan 20, 2021
Merged
43 changes: 28 additions & 15 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,28 +18,41 @@ 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 [email protected]:USERNAME/projectpythia.github.io.git
jukent marked this conversation as resolved.
Show resolved Hide resolved
```
- 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`.
Binary file added content/_static/images/ReadtheDocsAutobuild.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.