TJ Physics Olympiad Website

The repository for the TJ Physics Olympiad site

Developing

Installation

In order to work on the TJ Physics Olympiad site, you'll need to install git and uv.

After that, fork the repository. Next, clone the repository.

git clone https://github.com/your-github-user-name/tjpho
cd tjpho

Install the dependencies

uv run pre-commit install

To launch a live-reloading session, you can then do:

uv run just live

Navigate to http://localhost:8000/ to see the docs!

Making Edits

The website uses sphinx and the pydata sphinx theme. If you have any "complicated" stuff you want to do, check out the documentation of those two projects.

If you just want to edit content, you can edit the markdown files in the repository.

Tip

You can use sphinx directives to create special boxes for notes, important information, and much more!

After making your changes, make sure to run

uv run just build-strict

to make sure there are no issues with your changes.

Submitting Changes Upstream

You've made your changes on your computer, now how do you actually push them to the repository? First, switch to a new branch, if you haven't already:

git checkout main
git pull https://github.com/tjphysicsteam/tjpho.git main
git checkout -b patch-1

git add your changes. If you use an IDE like VS Code or Zed, there is a nice graphical way to do this. Otherwise, run this in the terminal.

git add .

Then commit your changes. Again, IDE's should have a graphical way to do this, but to do it in a terminal run:

git commit -m "A descriptive message about what you changed."

After this, a mini check will run to make sure stuff is formatted properly. If you encounter parsing errors, that means your syntax is invalid. Otherwise, you should just be able to run

git add .
git commit -m "A descriptive message about what you changed."

again, and it should work. After that, you have to push your changes:

git push

You have now submitted your changes on your fork! Navigate to https://github.com/tjphysicsteam/tjpho and create a pull request. Once the Physics Team webmaster finds time, they will review it and decide if it is acceptable to merge into main.

Deployment

Note

The following information is only relevant to the Physics Team officers (specifically the webmaster).

There is two github actions set up for the repository. The first runs continuous integration, to make sure the documentation build doesn't break.

The second will push the built documentation to a branch called static.

Before deploying, first create a new release on Github. After that continue on with deploying.

TJ Physics Team uses director4 to deploy our website, so navigate to director4, and open the editor. In the terminal, run:

cd public/olympiad

Ensure that it is on the static branch by running

git rev-parse --abbrev-ref HEAD

and making sure the output is static. Otherwise, run

git checkout static

Finally, to update the site, run

git pull

and check out the site at https://activities.tjhsst.edu/physics/olympiad

Maintenance

Updating dependencies

Most of the time, you can run uv lock -U to update dependencies.

To update python versions to version, say, 3.14, you can use uv python pin 3.14.