Skip to content

Commit fa6627a

Browse files
clyneandersy005jukentbrian-rose
authored
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>
1 parent efe0b80 commit fa6627a

File tree

4 files changed

+533
-48
lines changed

4 files changed

+533
-48
lines changed

.gitignore

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,6 @@ dmypy.json
132132
_build/
133133
_thumbnails/
134134
content/pages/communications.md
135-
content/pages/contributing.md
136135
content/pages/code_of_conduct.md
137136
content/pages/links.md
138137
content/pages/links/*.md

CONTRIBUTING.md

Lines changed: 73 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,87 @@
1-
# Contributor's Guide
1+
# Pythia Portal contributor's guide
22

3-
## Overview
3+
This document contains information specific to contributing to the
4+
Project Pythia Portal. Please first refer to [Pythia Contributor's
5+
Guide](https://projectpythia.org/pages/contributing.html) for overall
6+
contribution guidelines (such as detailed description of Project
7+
Pythia structure, forking, repository cloning, branching, etc.).
48

5-
Project Pythia is an open community, and all contributions are welcome following our [Code of Conduct](code_of_conduct.md).
9+
## Instructions for building the portal site
610

7-
The source code for the Pythia Portal is [publicly hosted on github](https://github.com/ProjectPythia/projectpythia.github.io).
8-
Contributions to open issues and new Pull Requests are welcome at any time.
9-
Detailed instructions for new users will be posted here in the near future.
11+
The portal site is built with [Sphinx](https://www.sphinx-doc.org/).
1012

11-
In the mean time, if you have links to some open educational content that you would like to include in the portal,
12-
feel free to [open an issue on github](https://github.com/ProjectPythia/projectpythia.github.io/issues)
13-
or contact any member of the [Project Pythia core team](people) directly.
13+
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
14+
below.
1415

15-
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).
16+
### Building the site
1617

17-
## Instructions for building the portal site
18+
After checking out a local copy of the site, in your favorite terminal, navigate to the `content` directory of the source repository
1819

19-
The portal site is built with [Sphinx](https://www.sphinx-doc.org/).
20+
```bash
21+
cd projectpythia.github.io/content
22+
```
23+
24+
Use [conda](https://docs.conda.io/) to set up a build environment:
25+
26+
```bash
27+
conda env create -f ../ci/environment.yml
28+
```
29+
30+
This will create or update the dev environment (`pythia`).
31+
32+
#### Install `pre-commit` hooks
33+
34+
This repository includes `pre-commit` hooks (defined in
35+
`.pre-commit-config.yaml`). To activate/install these pre-commit
36+
hooks, run:
37+
38+
```bash
39+
conda activate pythia
40+
pre-commit install
41+
```
42+
43+
Setting up the environment is typically a one-time step.
44+
45+
_NOTE_: The `pre-commit` package is already installed via the `pythia` conda environment.
2046

21-
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.
47+
#### Building the book locally
48+
49+
Build the site locally using Sphinx (which you just installed in the `pythia` environment, along with all necessary dependencies):
50+
51+
```bash
52+
make html
53+
```
54+
55+
The newly rendered site is now available in `content/_build/html/index.html`.
56+
Open with your web browser, or from the terminal:
57+
58+
```bash
59+
open _build/html/index.html
60+
```
61+
62+
However, many of the links will not work. For all of the links
63+
found in the portal to work properly, you'll need to set up a local
64+
testing server. This can be done with Python's http.server by running
65+
the following command from within the content directory:
66+
67+
```bash
68+
python -m http.server --directory _build/html/
69+
```
70+
71+
and then pointing your browser at the URL: localhost:8000.
72+
73+
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)
74+
75+
When you're done, you can deactivate the dedicated build environment with
76+
77+
```bash
78+
conda deactivate
79+
```
80+
81+
You can re-activate the `pythia` conda environment at any time with `conda activate pythia`.
2282

2383
### To view the Read the Docs autobuild
2484

2585
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.)
2686

2787
![Checks](../_static/images/ReadtheDocsAutobuild.png)
28-
29-
### To build and view the site locally
30-
31-
- Fork the [source repository](https://github.com/ProjectPythia/projectpythia.github.io) on GitHub
32-
- Make a local clone of the repository on your machine
33-
```bash
34-
git clone git@github.com:USERNAME/projectpythia.github.io.git
35-
# or
36-
git clone https://github.com/USERNAME/projectpythia.github.io.git
37-
```
38-
- In your favorite terminal, navigate to the `content` directory of the source repository
39-
```bash
40-
cd projectpythia.github.io/content
41-
```
42-
- Use [conda](https://docs.conda.io/) to set up a build environment:
43-
```bash
44-
conda env create -f ../ci/environment.yml
45-
conda activate pythia
46-
```
47-
- Build the site locally using Sphinx (which you just installed in the `pythia` environment, along with all necessary dependencies):
48-
```bash
49-
make html
50-
```
51-
- The newly rendered site is now available in `content/_build/html/index.html`.
52-
Open with your web browser, or from the terminal:
53-
```bash
54-
open _build/html/index.html
55-
```
56-
- When you're done, you can deactivate the dedicated build environment with
57-
```bash
58-
conda deactivate
59-
```
60-
- You can re-activate the `pythia` conda environment at any time with `conda activate pythia`.

content/conf.py

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,6 @@
8282
# Copy root files into content pages -----------------------------------------
8383

8484
shutil.copyfile('../CODEOFCONDUCT.md', 'pages/code_of_conduct.md')
85-
shutil.copyfile('../CONTRIBUTING.md', 'pages/contributing.md')
8685

8786
# Build Communication Channel Gallery ----------------------------------------
8887

0 commit comments

Comments
 (0)