Academic Map

A Jupyter Book of resources for open source in academia

Usage

Go to the website where this is rendered. Currently, that is here. You can also build this locally - see below.

Install

This is a Jupyter notebook, and depends on the tooling system of Jupyter Notebooks to work. Their documentation has an excellent intro to get started. For now:

• Clone this repository locally.
• Edit any Markdown locally.
• Add any pages that you want to be in the Table of Contents to _toc.yml.
• Run scripts/build.sh in order to automatically build the changes. You may need to run chmod +x scripts/build.sh to make this executable, first.

Development

Automatic Deployment

The site automatically builds and deploys when you push to the main branch. The GitHub Action (.github/workflows/deploy-book.yml) will:

1. Lint all markdown files (npm run lint)
2. Check all links (npm run links-ci)
3. Build the Jupyter book (jupyter-book build --all .)
4. Deploy to GitHub Pages

If any step fails, the deployment will stop and you'll receive a notification (if enabled in your GitHub notification settings).

Local Development

To work on the site locally:

# Install dependencies
npm install
pip install -r requirements.txt

# Lint markdown
npm run lint

# Check links
npm run links

# Check TOC completeness (ensures all files are in _toc.yml)
npm run check-toc

# Build the book locally
npm run build

# View the built site
open _build/html/index.html

Manual Deployment

If you need to manually deploy, you can use:

./scripts/build.sh

Contribute

Please! All contributions are welcome. As is written in the intro page currently:

• Open an issue to add data. If you are unsure how to use Git easily or you are unsure where something goes, just open an issue with your suggestions or comments.
• Add a page directly to the Git repository using a Pull Request. The GitHub repo is here. If you have a university, community, or so on, and you know how to use Git and GitHub, please open a PR with the resource!
• Complain. If this isn't working for you, tell us why, and we'd be more than happy to work to make it better.
• Ask in our community Head to the the Sustain Discourse.
• Send an email. Richard Littauer is the main editor for this repository, at the moment, and he's happy to incorporate any changes or to build a more welcoming and inclusive structure for collaboration here if any of the above options is less than ideal. Email richard@sustainoss.org.

Code of Conduct

By interacting with this repository you agree to the CODE_OF_CONDUCT.md.

License

MIT.

Disclaimer

This site was sponsored by the Alfred P. Sloan Foundation under Grant Number G-2023-21015. Any opinions, findings, conclusions or recommendations expressed herein are those of the author(s) and do not reflect the views of the Alfred P. Sloan Foundation or Carnegie Mellon University.