-
Notifications
You must be signed in to change notification settings - Fork 20
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* 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 <[email protected]> * 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 <[email protected]> Co-authored-by: Julia Kent <[email protected]> Co-authored-by: Brian Rose <[email protected]>
- Loading branch information
1 parent
efe0b80
commit fa6627a
Showing
4 changed files
with
533 additions
and
48 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 [email protected]: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`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.