Add initial documentation structure and contributing guide

Author: marcosfrenkel

.github/workflows/sphinx.yml

@@ -11,15 +11,14 @@ jobs:
     - uses: actions/checkout@v4
       with:
         persist-credentials: false
-    - name: Set up conda
-      uses: conda-incubator/setup-miniconda@v3
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v5
       with:
-        auto-activate-base: true
-        activate-environment: tfe-docs
-        environment-file: environment.yml
+        python-version: "3.13"
+    - name: Install dependencies
+      run: uv sync
     - name: Build HTML
-      shell: bash -l {0}
-      run: cd docs && make html
+      run: cd docs && uv run make html
     - name: Upload artifacts
       uses: actions/upload-artifact@v4
       with:
@@ -30,4 +29,4 @@ jobs:
       if: github.ref == 'refs/heads/main'
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: docs/build/html
+        publish_dir: docs/build/html

Makefile

@@ -0,0 +1,169 @@
+# Contributing
+
+A guide to contributing code to any of the Tools for Experiments repositories.
+
+---
+
+## Workflow overview
+
+### 1. Fork the repository
+
+Go to the GitHub page of the repository you want to contribute to and click **Fork** in the top-right corner. This creates a personal copy of the repo under your GitHub account.
+
+### 2. Clone your fork locally
+
+```bash
+git clone https://github.com/<your-username>/<repo-name>.git
+cd <repo-name>
+```
+
+### 3. Create a new branch
+
+Never commit directly to `main`. Create a dedicated branch for your changes:
+
+```bash
+git checkout -b my-feature-branch
+```
+
+Use a short, descriptive name (e.g. `fix-calibration-bug`, `add-sweep-tool`).
+
+### 4. Make your changes
+
+Edit the code, add new files, or fix bugs. Once you're happy with the changes, stage and commit them:
+
+```bash
+git add <files>
+git commit -m "Short description of what you changed"
+```
+
+### 5. Set up the environment with uv
+
+Each repository uses uv to manage its environment. From the root of the cloned repo, run:
+
+```bash
+uv sync
+```
+
+This installs all dependencies (including dev tools like `ruff`, `mypy`, and `pytest`) into a local `.venv`. You don't need to activate it — prefix every command with `uv run` and uv will use the right environment automatically.
+
+### 6. Run the checks locally
+
+Before pushing, run the three checks below to catch issues early. **The CI pipeline runs the same checks automatically and will block your pull request from merging if any of them fail.**
+
+Run all commands from the root of the repository (where `pyproject.toml` lives).
+
+#### Linting — ruff
+
+[ruff](https://docs.astral.sh/ruff/) checks code style and common errors:
+
+```bash
+uv run ruff check
+```
+
+The `.` (current directory) is implied when no path is given, so running `uv run ruff check` from the repo root checks all files in the project. To auto-fix issues where possible:
+
+```bash
+uv run ruff check --fix
+```
+
+#### Type checking — mypy
+
+[mypy](https://mypy.readthedocs.io/) checks for type errors:
+
+```bash
+uv run mypy
+```
+
+Again, run this from the repo root — mypy reads the project configuration from `pyproject.toml` and knows which files to check.
+
+Fix any reported type errors before submitting.
+
+#### Tests — pytest
+
+[pytest](https://docs.pytest.org/) runs the test suite:
+
+```bash
+uv run pytest
+```
+
+All tests must pass. If you added new functionality, add tests for it too.
+
+### 7. Push and open a pull request
+
+```bash
+git push origin my-feature-branch
+```
+
+Then go to your fork on GitHub and click **Compare & pull request**. Fill in a description of what your changes do and why, then submit.
+
+The CI pipeline will run `ruff`, `mypy`, and `pytest` automatically. You can follow the results in the **Checks** tab of your pull request. All checks must pass before the PR can be merged.
+
+---
+
+## Contributing to the documentation
+
+The docs are written in Markdown using [MyST](https://myst-parser.readthedocs.io/) and built with [Sphinx](https://www.sphinx-doc.org/). Every page is a `.md` file inside the `docs/` directory.
+
+### How the docs are organized
+
+```
+docs/
+├── conf.py          # Sphinx configuration
+├── index.md         # Top-level table of contents
+├── guides/
+│   ├── index.md     # Section table of contents
+│   └── *.md         # Individual guide pages
+├── contributing/
+│   └── *.md
+└── examples/
+    └── *.md
+```
+
+Each `index.md` contains a `{toctree}` directive that lists the pages in that section. When you add a new page, register it there.
+
+### Adding a new page
+
+1. Create a new `.md` file in the appropriate section folder.
+2. Add its filename (without extension) to the `{toctree}` in that folder's `index.md`:
+
+   ````markdown
+   ```{toctree}
+   :maxdepth: 2
+
+   existing-page
+   your-new-page
+   ```
+   ````
+
+### Editing an existing page
+
+Just edit the `.md` file directly — it is plain Markdown with optional MyST directives.
+
+### Building the docs locally
+
+The docs repo has its own `pyproject.toml` at the root of `toolsforexperiments/` that includes Sphinx and its dependencies. First sync the environment:
+
+```bash
+uv sync
+```
+
+Then build the HTML from the `docs/` directory:
+
+```bash
+cd docs
+uv run make html
+```
+
+The output is written to `docs/build/html/`. Open `docs/build/html/index.html` in your browser to preview the result:
+
+```bash
+open docs/build/html/index.html   # macOS
+xdg-open docs/build/html/index.html  # Linux
+```
+
+To do a clean rebuild from scratch (useful if pages aren't updating):
+
+```bash
+cd docs
+uv run make clean html
+```