The community knowledge base for UC Berkeley Astronomy graduate students.
Live site: badgrads.github.io/BadGradWiki
BadGradWiki is a Sphinx-based documentation site maintained by graduate students in the UC Berkeley Astronomy Department. It collects practical knowledge, shared experience, and institutional memory to help grads navigate the department, the PhD program, and life in Berkeley.
Note
This wiki is maintained by graduate students, for graduate students. It does not represent official department or university policy.
| Section | Description | Link |
|---|---|---|
| Department Roles | Grad-run service jobs — who does what, expectations, and advice from past holders | Explore Roles → |
| Teaching & GSI Resources | Resources for GSIs: course logistics, pedagogy advice, and shared materials | Teaching Resources → |
| Life in Berkeley | Housing, healthcare, transportation, finances, and daily life as a Berkeley grad | Grad Life → |
| The PhD Program | Prelims, quals, milestones, advising, pay, and navigating the program | Program Resources → |
| Science & Computing | Computing resources, remote observing, and technical guides | Science & Computing → |
- Python 3.8+
- Git
Clone the repository and run the setup script from the repo root:
git clone git@github.com:BadGrads/BadGradWiki.git
cd BadGradWiki
./source_env.shThis creates (or updates) a .venv virtual environment and installs all dependencies from
requirements.txt. If python3 is not the right executable on your system:
./source_env.sh --python /path/to/pythonAll build commands run from the wiki/ directory:
cd wiki
make html # build → wiki/build/html/index.html
make clean # remove build artifacts
make help # list all available buildersOpen wiki/build/html/index.html in a browser to preview. The build must complete with
no errors or warnings before a PR is submitted.
BadGradWiki is a community effort — its usefulness depends entirely on contributions from current and former graduate students. Contributions of any size are welcome, from fixing a typo to adding a whole new section.
The short version:
- Fork the repo (or clone directly and create a branch)
- Run
./source_env.shto set up your environment - Make your changes in
wiki/source/ - Build locally with
make htmland verify there are no warnings - Commit using Conventional Commits — this is enforced by a pre-commit hook
- Open a pull request against
main
For the full workflow, see the Contributing Guide on the live site.
Commits are enforced by Commitizen via a pre-commit hook. Messages must follow Conventional Commits:
docs: add new section on grad life housing
fix: correct broken link in teaching index
chore: update sphinx dependency version
The repo uses pre-commit for automated checks on every commit:
| Hook | Purpose |
|---|---|
check-merge-conflict |
Catches unresolved merge conflicts |
check-yaml / check-toml |
Validates config file syntax |
end-of-file-fixer |
Ensures files end with a newline |
trailing-whitespace |
Strips trailing whitespace |
typos |
Spell-checks source files |
commitizen |
Enforces Conventional Commits format |
Most hooks auto-fix issues — if a commit is rejected, re-stage the modified files and try again.
| Tool | Role |
|---|---|
| Sphinx | Documentation engine |
| pydata-sphinx-theme | Site theme |
| sphinx-design | Cards, grids, and UI components |
| MyST Parser | Markdown support alongside RST |
| sphinxcontrib-bibtex | BibTeX references |
| sphinx-last-updated-by-git | Auto git-commit timestamps on pages |
| pre-commit + Commitizen | Commit quality hooks |
Reach out to the current BadGradWiki administrators (listed on the Department Roles page), or open an issue on GitHub.