deploy: 5475b47

Author: marcosfrenkel

_sources/guides/contributing.md.txt

@@ -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
+```

_sources/guides/environment_setup.md.txt

@@ -0,0 +1,214 @@
+# Setting Up Your Environment
+
+A guide to getting your development environment set up for working with Tools for Experiments.
+
+---
+
+## Option 1: Using uv
+
+### What is uv?
+
+[uv](https://docs.astral.sh/uv/) is a fast Python package and project manager written in Rust, developed by Astral (the team behind `ruff`). It serves as a drop-in replacement for `pip`, `pip-tools`, `virtualenv`, and more — but orders of magnitude faster.
+
+Key concepts:
+- **`pyproject.toml`**: The single source of truth for your project's dependencies and metadata, following the modern Python packaging standard.
+- **`uv.lock`**: A lockfile automatically generated by uv that pins exact versions of all dependencies (direct and transitive) for reproducible environments.
+- **Editable installs**: uv supports installing local packages in editable mode (`editable = true`), meaning changes to the source code of those packages are immediately reflected without reinstalling.
+- **Virtual environments**: uv automatically creates and manages a `.venv` in your project directory.
+
+### Installing uv
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Or via pip:
+
+```bash
+pip install uv
+```
+
+### Project structure: `pyproject.toml`
+
+Each measurement or experiment folder should have a `pyproject.toml` that declares its dependencies. For packages that live locally on your machine (like `instrumentserver` or `labcore`), use `[tool.uv.sources]` to point uv to their local paths with editable installs:
+
+```toml
+[project]
+name = "testing-uv-env"          # (1) change to your project name
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "instrumentserver",           # (2) list every package you need here
+    "labcore",                    #     one string per package, comma-separated
+]
+
+[tool.uv.sources]
+# (3) for each local package listed above, add an entry here pointing to its
+#     location on your machine. Paths are relative to this pyproject.toml file.
+instrumentserver = { path = "../../github/instrumentserver", editable = true }
+labcore = { path = "../../github/labcore", editable = true }
+```
+
+**What you need to change:**
+
+1. **`name`** — set it to something that identifies your experiment or measurement folder.
+
+2. **`dependencies`** — list all packages your code needs. Regular PyPI packages (e.g. `numpy`, `matplotlib`) just go here as plain strings and uv will fetch them automatically. Local packages also go here — they need a matching entry in `[tool.uv.sources]`.
+
+3. **`[tool.uv.sources]`** — for every local package in `dependencies`, add a line with the relative path from this `pyproject.toml` to that package's root directory (the folder that contains its own `pyproject.toml` or `setup.py`). Keep `editable = true` so that code changes in those repos take effect immediately.
+
+For example, if your experiment folder is at `~/projects/my-experiment/` and `labcore` is cloned at `~/github/labcore/`, the relative path would be `../../github/labcore`.
+
+### Creating and syncing the environment
+
+From the directory containing your `pyproject.toml`, run:
+
+```bash
+uv sync
+```
+
+This will:
+1. Create a `.venv` virtual environment in the current directory (if it doesn't exist).
+2. Install all dependencies listed in `pyproject.toml`.
+3. Install the local editable packages from the paths defined in `[tool.uv.sources]`.
+4. Generate or update `uv.lock`.
+
+### Activating the environment
+
+```bash
+source .venv/bin/activate
+```
+
+Or run commands directly without activating:
+
+```bash
+uv run python my_script.py
+uv run jupyter lab
+```
+
+### Adding new dependencies
+
+```bash
+uv add some-package
+```
+
+This updates `pyproject.toml` and `uv.lock` automatically.
+
+---
+
+## Option 2: Using conda / mamba
+
+[conda](https://docs.conda.io/) is a cross-platform package and environment manager. [mamba](https://mamba.readthedocs.io/) is a faster drop-in replacement for conda that uses the same commands and environment files.
+
+### Installing conda or mamba
+
+- **Miniforge** (recommended — ships with mamba by default):
+  Download from [github.com/conda-forge/miniforge](https://github.com/conda-forge/miniforge/releases) and follow the installer instructions.
+
+- **Miniconda** (conda only):
+  Download from [docs.conda.io/en/latest/miniconda.html](https://docs.conda.io/en/latest/miniconda.html).
+
+### Creating an environment from the provided file
+
+A base `environment.yml` is provided at the root of this repository with a standard set of dependencies:
+
+```yaml
+name: labcore
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.10
+  - jupyterlab
+  - jupyter_bokeh
+  - qcodes=0.44.1
+  - bokeh
+  - pandas
+  - xarray
+  - matplotlib
+  - numpy=1.26.4
+  - scipy
+  - scikit-learn
+  - seaborn
+  - lmfit
+  - h5py=3.10.0
+  - xhistogram
+  - holoviews
+  - panel
+  - param
+  - hvplot
+  - versioningit
+  - qtpy
+  - pip
+  - gitpython
+  - watchdog
+  - pywavelets
+```
+
+To create the environment from it, run from the root of the repository:
+
+```bash
+conda env create -f environment.yml
+conda activate labcore
+```
+
+With mamba (faster):
+
+```bash
+mamba env create -f environment.yml
+mamba activate labcore
+```
+
+### Adding or changing dependencies
+
+If you need extra packages not in `environment.yml`, install them into the active environment:
+
+```bash
+conda install -c conda-forge some-package
+```
+
+For packages only available on PyPI:
+
+```bash
+pip install some-package
+```
+
+### Installing local packages in editable mode
+
+For local repositories like `instrumentserver` or `labcore`, install them in editable mode using pip. Replace the paths below with the actual location of each repo on your machine:
+
+```bash
+pip install -e /path/to/instrumentserver
+pip install -e /path/to/labcore
+```
+
+For example, if your repos live in `~/github/`:
+
+```bash
+pip install -e ~/github/instrumentserver
+pip install -e ~/github/labcore
+```
+
+The `-e` flag means editable — any changes you make to the source code of those packages are immediately active without needing to reinstall.
+
+### Exporting and sharing your environment
+
+To export your environment so others can reproduce it:
+
+```bash
+conda env export > environment.yml
+```
+
+To recreate it from the file:
+
+```bash
+conda env create -f environment.yml
+```
+
+For a more portable export (cross-platform, without build strings):
+
+```bash
+conda env export --no-builds > environment.yml
+```

_sources/guides/index.md.txt

@@ -0,0 +1,11 @@
+# Guides
+
+General guides and resources for working within the Tools for Experiments organization.
+
+```{toctree}
+:maxdepth: 2
+
+organization
+environment_setup
+contributing
+```