Tweaks for management and docs

.github/workflows/codestyle.yml

@@ -0,0 +1,37 @@
+name: Code Style
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install uv and set the Python version
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.11'
+          enable-cache: true
+
+      - name: Install dev dependencies
+        run: |
+          EXTRAS="--extra dev"
+          uv sync --locked ${EXTRAS}
+
+      - name: Check code style with ruff
+        run: |
+          set -o errexit
+          uv run ruff check --fix . --config ./pyproject.toml
+          uv run ruff format . --config ./pyproject.toml

.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+# repos:
+# - repo: https://github.com/asottile/pyupgrade
+#   rev: v3.21.2
+#   hooks:
+#     - id: pyupgrade
+#       args: [--py310-plus]
+#       files: '\.py$'
+# - repo: https://github.com/astral-sh/uv-pre-commit
+#   rev: 0.9.14
+#   hooks:
+#     - id: uv-lock
+# - repo: https://github.com/astral-sh/ruff-pre-commit
+#   # Ruff version.
+#   rev: v0.14.7
+#   hooks:
+#     # Run the linter.
+#     - id: ruff
+#       types_or: [ python, pyi, jupyter ]
+#       args: [ --fix ]
+#     # Run the formatter.
+#     - id: ruff-format
+#       types_or: [ python, pyi, jupyter ]

.readthedocs.yaml

@@ -0,0 +1,30 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+# Install Python dependencies using uv when available, pip as fallback
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev
+
+# Build pull request previews
+# This enables documentation builds for pull requests
+formats:
+  - pdf
+  - htmlzip

codecov.yml

@@ -0,0 +1,17 @@
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 5%
+        base: auto
+
+comment:                  # this is a top-level key
+  layout: "condensed_header, reach, diff, flags, condensed_files, condensed_footer"
+  behavior: default
+  require_changes: false
+  require_base: true
+  require_head: false
+  hide_project_coverage: false
+  after_n_builds: 1
+  show_carryforward_flags: true

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,162 @@
+# qp-planck Documentation
+
+This directory contains the Sphinx documentation source for **qp-planck**.
+
+## Building Locally
+
+1. Install dependencies (from project root):
+   ```bash
+   # Using uv (recommended)
+   uv sync --all-extras
+
+   # Or using pip
+   pip install -e ".[dev]"
+   ```
+
+2. Build HTML documentation:
+   ```bash
+   cd docs
+   uv run sphinx-build -b html . _build/html
+   # Or: make html
+   ```
+
+3. View the documentation:
+   ```bash
+   open _build/html/index.html
+   ```
+   (Or use your browser to navigate to `_build/html/index.html`)
+
+## Building on Read the Docs
+
+The documentation is automatically built on Read the Docs when changes are
+pushed to the repository. Configuration is in `../.readthedocs.yaml`.
+
+## Documentation Structure
+
+```
+docs/
+├── index.rst               # Main landing page
+├── installation.rst        # Installation guide
+├── quickstart.rst         # Quick start tutorial
+├── physics_background.rst # Theory and formalism
+├── configuration.rst      # Python API configuration
+├── yaml_config.rst        # YAML configuration guide
+├── examples.rst           # Example workflows
+├── contributing.rst       # Contribution guidelines
+├── changelog.rst          # Version history
+├── references.rst         # Bibliography and links
+├── api/                   # API reference
+│   ├── utilities.rst
+│   ├── hmap2mat.rst
+│   ├── mat2fits.rst
+│   └── pipeline.rst
+├── conf.py               # Sphinx configuration
+└── Makefile              # Build automation (Unix)
+```
+
+## Writing Documentation
+
+### RST Syntax
+
+We use reStructuredText (.rst) format. Key syntax:
+
+**Headers:**
+```rst
+Title
+=====
+
+Section
+-------
+
+Subsection
+^^^^^^^^^^
+```
+
+**Code blocks:**
+```rst
+.. code-block:: python
+
+   from qp_planck import load_RIMO
+   RIMO = load_RIMO("path/to/file.fits")
+```
+
+**Cross-references:**
+```rst
+See :doc:`installation` for setup instructions.
+See :func:`qp_planck.load_RIMO` for API details.
+```
+
+**Math:**
+```rst
+.. math::
+
+   C_\ell^{\text{obs}} = C_\ell^{\text{sky}} \cdot W_\ell
+```
+
+### Adding New Pages
+
+1. Create `new_page.rst` in `docs/`
+2. Add to table of contents in `index.rst`:
+   ```rst
+   .. toctree::
+      :maxdepth: 2
+
+      new_page
+   ```
+3. Build and verify
+
+### Docstrings
+
+API documentation is automatically generated from docstrings in the source code.
+Use Google-style docstrings:
+
+```python
+def my_function(param: str) -> int:
+    """Brief one-line description.
+
+    Longer description with details.
+
+    Parameters
+    ----------
+    param : str
+        Description of parameter.
+
+    Returns
+    -------
+    int
+        Description of return value.
+
+    Examples
+    --------
+    >>> my_function("test")
+    42
+    """
+    pass
+```
+
+## Cleaning Build Artifacts
+
+```bash
+make clean
+```
+
+## Troubleshooting
+
+**Import errors during build:**
+- Ensure all dependencies are installed: `uv sync --all-extras`
+- Check that the package is installed in development mode
+
+**Missing modules in API docs:**
+- Run `make clean` then `make html` to rebuild from scratch
+- Check that modules are listed in `conf.py` extensions
+
+**Math not rendering:**
+- Ensure MathJax is configured in `conf.py`
+- Use proper LaTeX syntax in math blocks
+
+## Resources
+
+- [Sphinx documentation](https://www.sphinx-doc.org/)
+- [RST primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
+- [Read the Docs](https://docs.readthedocs.io/)
+- [Sphinx RTD theme](https://sphinx-rtd-theme.readthedocs.io/)