Standardize NumPy-style docstrings and add Sphinx + GitHub Pages docs publishing

[Copilot]

This PR aligns the codebase docstrings with NumPy conventions and fills missing/incomplete API documentation. It also adds a minimal documentation toolchain for autogenerated API docs and a GitHub Actions workflow to publish docs to GitHub Pages.

• Docstring standardization (NumPy style)

  • Normalized section structure across core modules (Parameters, Returns, Raises, etc.).
  • Added missing module/class/function/method docstrings in public API surfaces.
  • Corrected incomplete or malformed docstrings so autodoc can parse consistently.

• Autogenerated documentation

  • Added a Sphinx docs scaffold:
    • docs/conf.py
    • docs/index.rst
    • docs/api.rst
    • docs/requirements.txt
  • Enabled autodoc + autosummary + napoleon for API pages generated from source docstrings.

• Docs publishing pipeline

  • Added .github/workflows/docs.yml to:
    • build documentation on main pushes / manual dispatch
    • upload built HTML as Pages artifact
    • deploy to GitHub Pages

• README update

  • Replaced placeholder docs section with concrete local build command and notes on auto-generated API docs + Pages publishing.

Example (autodoc-backed API page entry):

.. automodule:: rxmc.params
   :members:
   :undoc-members:
   :show-inheritance:

Generated docs UI (index + API navigation):
https://github.com/user-attachments/assets/d51dea1e-eb62-4cc0-a396-54e8afb06cc8

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[Copilot]

Pull request overview

This PR standardizes Python docstrings toward a NumPy/Sphinx-friendly structure across the rxmc package and introduces a minimal Sphinx documentation toolchain with automated GitHub Pages publishing.

Changes:

• Normalize/expand module + API docstrings across core rxmc modules for autodoc consumption.
• Add Sphinx scaffold (docs/) for API reference generation using autodoc/autosummary/napoleon.
• Add a GitHub Actions workflow to build and deploy docs to GitHub Pages, and update README with local build instructions.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/rxmc/walker.py	Updates docstrings and adds brief method docstrings for posterior/likelihood helpers.
src/rxmc/proposal.py	Adds module docstring and reformats proposal distribution docstrings.
src/rxmc/physical_model.py	Reworks class/method docstrings to be more Sphinx/Napoleon-friendly.
src/rxmc/params.py	Adds module/function docstrings for parameter/sample serialization helpers.
src/rxmc/param_sampling.py	Reformats sampler docstrings to match the updated style.
src/rxmc/observation_from_measurement.py	Adds module docstring and documents angle-grid validation helper.
src/rxmc/observation.py	Adds module docstring and small utility/method docstrings.
src/rxmc/metropolis_hastings.py	Converts function docstring to a NumPy-style section layout.
src/rxmc/likelihood_model.py	Updates docstring section headers and documents covariance scaling helper.
src/rxmc/ias_pn_observation.py	Adds module docstring and documents wrapper/delegate methods + angle-grid validation.
src/rxmc/ias_pn_model.py	Reformats model docstrings for Sphinx parsing.
src/rxmc/evidence.py	Adds module docstring.
src/rxmc/elastic_diffxs_observation.py	Adds module docstring and documents wrapper/delegate methods.
src/rxmc/elastic_diffxs_model.py	Reformats model docstrings for Sphinx parsing.
src/rxmc/correlated_discrepancy_likelihood_model.py	Adds module/method docstrings and removes trailing whitespace.
src/rxmc/constraint.py	Reformats constraint docstrings to NumPy-style sections.
src/rxmc/adaptive_metropolis.py	Adds module docstring and adjusts function docstring section header.
src/rxmc/init.py	Adds package-level module docstring.
docs/requirements.txt	Adds minimal docs dependency pin (Sphinx).
docs/index.rst	Adds docs landing page with toctree.
docs/conf.py	Adds Sphinx configuration with autodoc/autosummary/napoleon enabled.
docs/api.rst	Adds automodule-based API reference page covering core modules.
README.md	Replaces placeholder docs section with local build instructions and Pages notes.
.github/workflows/docs.yml	Adds CI workflow to build docs and deploy to GitHub Pages.

Comments suppressed due to low confidence (3)

src/rxmc/walker.py:214

• The walk docstring’s Parameters section has the parameter entries (n_steps, batch_size, etc.) indented relative to the section header. With NumPy-style docstrings, parameter names should start at the left margin under the section header; the current indentation can prevent napoleon from recognizing the parameters list and can break the generated API docs.

        Parameters
        ----------
            n_steps : int
                Total number of active steps for the MCMC chain.
            batch_size : int
                Number of steps per batch.

src/rxmc/observation_from_measurement.py:134

• check_angle_grid claims/enforces an angle domain of [0, pi) (see docstring and error message), but the actual check uses angles_rad[-1] > np.pi, which allows an endpoint exactly equal to np.pi. Either tighten the check to exclude np.pi (e.g., >= np.pi) or update the docstring/error message to match the inclusive behavior.

def check_angle_grid(angles_rad: np.ndarray, name: str):
    """Validate that ``angles_rad`` is 1D and bounded on ``[0, pi)``."""

    if len(angles_rad.shape) > 1:
        raise ValueError(f"{name} must be 1D, is {len(angles_rad.shape)}D")
    if angles_rad[0] < 0 or angles_rad[-1] > np.pi:
        raise ValueError(f"{name} must be on [0,pi)")

src/rxmc/ias_pn_observation.py:225

• check_angle_grid docstring/error message specify [0, pi), but the implementation checks angles_rad[-1] > np.pi, which permits an endpoint exactly equal to np.pi. Please either change the predicate to enforce the stated half-open interval or adjust the documentation/message to reflect the inclusive bound.

def check_angle_grid(angles_rad: np.ndarray, name: str):
    """Validate that ``angles_rad`` is 1D and bounded on ``[0, pi)``."""

    if len(angles_rad.shape) > 1:
        raise ValueError(f"{name} must be 1D, is {len(angles_rad.shape)}D")
    if angles_rad[0] < 0 or angles_rad[-1] > np.pi:
        raise ValueError(f"{name} must be on [0,pi)")

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

dump_samples_to_numpy calls list_to_array(samples) without providing the required params_dtype argument, which will raise a TypeError at runtime. Update this helper (and/or list_to_array) so the dtype can be provided or inferred before saving.

[Copilot]

read_samples_from_numpy calls array_to_list(np.load(fpath)) but array_to_list requires a params list to map columns back to parameter names. As written this will raise a TypeError (and the function can’t produce correct keys without params). Consider adding a params argument to read_samples_from_numpy, or persisting/loading the parameter names alongside the .npy data.

Suggested change

	def read_samples_from_numpy(fpath: Path):
	"""Read samples from a NumPy ``.npy`` file."""
	return array_to_list(np.load(fpath))
	def read_samples_from_numpy(fpath: Path, params: list):
	"""Read samples from a NumPy ``.npy`` file."""
	return array_to_list(np.load(fpath), params)

[Copilot]

In this docstring, the Parameters section header is indented more than the rest of the docstring text (it’s nested under the summary line). After docstring dedenting, this typically causes Sphinx (napoleon/numpydoc) to treat the section as a literal block and skip parsing it. Align Parameters/---------- with the other top-level docstring lines (no extra indent).

[Copilot]

The docs toolchain declares sphinx>=8 in docs/requirements.txt, and this file is installed in CI by the docs GitHub Actions workflow, so arbitrary future sphinx releases (or a compromised package with that name) will be executed in a privileged Actions environment. This creates a supply-chain risk where a malicious sphinx release could run code during the docs build and exfiltrate GITHUB_TOKEN or tamper with published documentation. To mitigate this, pin sphinx to a specific, trusted version (and update it via an automated dependency updater) so CI always uses a known-good release.