https://www.pyopensci.org/peer-review-guide/
pyOpenSci's guide for developing, reviewing, and maintaining packages.
We welcome issues and pull requests to improve the content of this guide. If you'd like to see an improvement, please open an issue.
To submit a Pull Request with changes:
- Create a fork of this repo to make changes.
- After making changes, build the book locally from your fork to preview the changes to make sure they appear as expected (see How to build the guide locally below)
- When satisfied, push the changes back to GitHub and open a pull request from your fork to the main branch of this repo.
- The Continuous Integration processes will build the book and let you and the PR reviewer(s) preview it in your browser (see Automated build and publishing below).
- The reviewer of the PR may request modifications.
- Once satisfied, the reviewer will merge your pull request! Thanks for your contribution!
The pyOpenSci guidebook is written using Jupyter Book.
To build the guide locally, take the following steps:
-
Clone this repository (or clone your fork by replacing "pyOpenSci" with your GitHub username):
git clone https://github.com/pyOpenSci/peer-review-guide
To build, follow these steps:
- Install
nox
pip install nox- Build the documentation:
nox -s docsThis should create a local environment in a .nox folder, build the documentation (as specified in the noxfile.py configuration), and the output will be in _build/html.
To build live documentation that updates when you update local files, run the following command:
$ nox -s docs-live- To view your built book:
Navigate to _build/html/ on your local clone of the repo and open "index.html".
Whenever a pull request is opened or changes are pushed to any branch of the base repository, the book is built (separately) by both GitHub Actions and CircleCI.
- GitHub Actions is the main build tool. In addition to building whenever a pull request is opened from a fork, it handles publishing the book when changes are made to the main branch (e.g. once the pull request is merged). When that happens, it pushes the built html files to the gh-pages branch, which publishes the book to the website.
- CircleCI's build is redundant, but it offers an easier way of viewing the built html in browser WITHOUT merging the changes to main or downloading files. See How do you preview the the guide from a Pull Request below for details.
- (Recommended) Via the artifact redirector workflow: When viewing the checks in a pull request, click "Details" next to the "Click to preview rendered book" to be automatically taken to the CircleCI index.html preview. This is performed using the circleci-artifacts-redirector-action workflow. See the gif below for a demonstration.
- Via CircleCI: Go to the CircleCI job and select the "Artifacts" tab. Click on "index.html" to preview the built book.
- Via GitHub Actions alone: GitHub Actions also saves the built html files for preview, but you have to download and unzip the files to your local computer. Go to your deploy-book build in the Actions tab. Then select "book-html" in the "Artifacts" pane near the bottom of the page. After downloading, unzip the book-html.zip file into a separate directory and open "index.html" from the directory with the unzipped files. The book should open in your web browser.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!