pybamm.org

Source code for pybamm.org, released under the BSD-3-Clause License.

Steps to contribute

Tip

Gitpod can also be used to contribute to the website. To do so, click on the Gitpod button above to open the repository in an online text editor (Visual Studio Code). Once the workspace is ready, you can follow a subset of the steps below to contribute to the website. You can learn more about Gitpod here: https://www.gitpod.io/docs/introduction/getting-started

1. Fork this repository
2. Install the extended version of Hugo from https://gohugo.io/installation/ and dart-sass and add them to your PATH
3. Clone your forked repository and add the theme repository as a submodule, from https://github.com/scientific-python/scientific-python-hugo-theme. You may update the submodule and pull the latest changes with

git submodule update --init --recursive

or clone directly with

git clone --recurse-submodules https://github.com/pybamm-team/pybamm.org.git

4. Create pages and run the server locally with

nox

or alternatively

nox -s html
nox -s serve

In development mode, run the server with

nox -s html
nox -s serve-dev

You may use nox -s clean to clean up build artefacts.

5. Before committing your changes, install prek, update the hooks, and run with

pip install prek
prek install

to ensure that there are no style errors before committing your changes. The current hooks provide support for checking spelling errors and typos, Markdown style, and common file-based issues.

Rather than just the files changed due to a commit, you may run the hooks on all files using the prek -a/prek --all-files command.

You may use a shorthand nox -s lint to do the same, though you'll need to install prek manually separately.

6. To generate the teams page, run

nox -s teams

It is recommended to verify the changes to the teams page before committing. The teams page is generated from the files in static/teams/ and the script scripts/get_teams_info.py and the output is displayed in content/teams.md.

Caution

The nox -s teams command will overwrite the files in the static/teams/ directory.

Alternatively, the teams page can be generated via a pull request by manually triggering the teams.yml workflow.

7. To add a news item, create a new .md file in content/news/YYYY/MM/DD/ with the following YAML frontmatter

---
title: "Title of the news item"
date: YYYY-MM-DD
summary: "Summary of the news item"
---

The newsHeader parameter will automatically be set to the title: of the latest news item and will show up on the homepage of the website.

Deployment

The website is built using the Hugo static site generator and is hosted on Netlify.

Style guidelines (shortcodes, content, etc.)

Some shortcodes for adding general-purpose buttons and links are available in layouts/shortcodes/ and can be used as follows:

{{< name-of-shortcode shortcode-parameters >}}

2. There are also special shortcodes: external-pybamm-changelog-content and external-content-simple to avoid truncated data from the GitHub API v.s. what is served by the raw GitHub CDN URLs. They are used only for the Code of Conduct and the CHANGELOG pages, respectively. We use the GitHack CDN to serve the contents for these pages. The content is stored in the main PyBaMM repository on GitHub and is automatically updated when the file in the repository is changed. The title MUST be present in the frontmatter, since Hugo has to use it at build time, not runtime.

3. To change how things look, edit assets/css/overrides.css or add any additional CSS file to the assets/css/ directory. These files are loaded after the theme-specific CSS files, so they can be used to override any styles set by the theme.

For more information, please refer to the Hugo documentation and the Scientific Python Hugo theme guides.

Analytics

The website uses a privacy-friendly analytics service called Plausible. The analytics data is available for authorised users at https://plausible.io/pybamm.org.