Website maintenance

This website is currently developed and maintained via Gitlab. It was migrated from the Oden Institute SVN server on Feb 2026.

How the Gitlab repo is organized

  • content/ : contains ReStructuredText source files and

    • content/images/ : images;

    • content/PDFs/ : PDFs;

  • css/ : contain static assets;

  • build/ : contains the local build output (not tracked), used to check the website locally before pushing;

  • .gitlab-ci.yml : contains CI/CD pipeline configuration and page encryption;

  • .gitattributes : makes sure all images, PDFs, tarballs, etc are stored via Gitlab LFS;

  • .gitignore : contains the list of objects that should not be committed to the repo;

  • crypt.sh : needed for page encryption;

  • main : production branch, published as docs.epw-code.org.

Getting started

Clone the repo

git clone git@gitlab.com:epw/epw-website.git
cd epw-website

Note

In the SVN era we were committing large files to the repo, and the size reached 2 GB. To make it manageable with Gitlab, the old files/ folder was migrated to Google Drive. Even with this trimming, the repository is still somewhat bloated (270 MB as of Feb 2026). Please help keeping this repo lean by using Google Drive links (see Rules and repository hygiene).

Create Python virtual environment

Create the virtual environment:

python3 -m venv .venv

Activate the environment. In bash/zsh:

source .venv/bin/activate

or in csh/tcsh:

source .venv/bin/activate.csh

Install Sphinx and Piccolo theme:

pip install sphinx
pip install piccolo-theme

If Sphinx and Piccolo have already been installed, skip the above installation steps and simply activate the environment:

source .venv/bin/activate

Build the website locally

From the repository root:

sphinx-build -b html content/ build/html

The site will be generated in:

build/html/

Open locally in a browser, for example:

firefox build/html/index.html

Development workflow

All modifications must follow a branch + merge request model, as in the EPW code repository. Direct pushes to main are not allowed.

Create your branch (after pulling the main)

git checkout main
git pull
git checkout -b my_branch

Examples:

  • developername_update_contacts

  • developername_update_releases

Make changes and commit

git add -A
git commit -m "description of changes"

Push Branch

git push origin my_branch

Open a merge request

On GitLab:

  1. Create a merge request.

  2. Target branch: main.

  3. Describe changes.

Merge into main will be performed by maintainers once the MR is approved.

Clean up

git checkout main
git pull
git branch -d my_branch

Deployment model

  • main is the production branch.

  • GitLab CI automatically builds, encrypts, and deploys the website.

  • Each merge into main triggers deployment.

  • The two pages containing developer meeting and steering committee materials are password-protected upon deployment (not upon local build).

Rules and repository hygiene

In the past, the previous SVN repository became bloated because very large files were added to the SVN repo. This caused problems during migration to GitLab. To avoid this going forward, follow these rules:

  1. Only .rst files inside content/ should be modified, added, or removed.

  2. If you need to upload a PDF, do not add it PDF to this repository. Instead upload the file on this Google Drive folder and create a link to this file.

  3. Image files should not exceed 100 KB. To compress images without noticeable quality loss, you can use squoosh. Images should be placed under /images, possibly within a new subfolder with a recognizable name.

  4. If moving files or folders, use:

    git mv file1 file2

    This updates headers without unnecessarily duplicating files and bloating the repository history.

FG, 12 Feb 2026