Skip to content

Docs/mkdocs migration - #119

Open
corentinravoux wants to merge 9 commits into
mainfrom
docs/mkdocs-migration
Open

Docs/mkdocs migration#119
corentinravoux wants to merge 9 commits into
mainfrom
docs/mkdocs-migration

Conversation

@corentinravoux

@corentinravoux corentinravoux commented Jul 30, 2026

Copy link
Copy Markdown
Owner

No description provided.

Copilot AI review requested due to automatic review settings July 30, 2026 09:15
corentinravoux and others added 4 commits July 30, 2026 11:15
@corentinravoux @claude
docs(pydoc): complete docstrings across mature subpackages
c8c0389 
Insert-only docstring pass over the mature subpackages (data_vector,
power_spectra, covariance) plus top-level modules (utils, _config,
_subpackages, data/load_data_test). Adds missing function/class/module
docstrings and per-model descriptions for every analytical covariance
model, excluding the generated flip_terms/coefficients/fisher_terms
(and symbolic term-generation) files as requested. No executable code
changed: AST with docstrings stripped is byte-identical to the parent
for all 44 touched files.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@corentinravoux @claude
docs: migrate documentation from Sphinx/ReadTheDocs to MkDocs
7501ad3 
Replace the ReadTheDocs (Sphinx) documentation with a MkDocs Material
site built from the in-code docstrings via mkdocstrings, matching the
format used across the sibling packages.

- Remove the Sphinx system: conf.py, all .rst sources, docs/api,
  docs/_templates, docs/_static, .readthedocs.yaml; swap the pyproject
  [docs] extra from Sphinx to mkdocs-material + mkdocstrings.
- Migrate and update every existing page (installation, getting started,
  DataVector, velocity estimators, likelihoods, power spectra) to the
  current API, and extend coverage to the whole mature package:
  covariance models (with the full analytical-model registry), fitting &
  forecasts (Minuit / MCMC / Fisher), and per-subpackage API pages.
  Estimator keys, class names (VelTrippRelation), and fitter/likelihood
  signatures updated to match the code; all code examples verified.
- Preserve the logo under docs/assets; keep the doc structure/logic of
  the previous site (install -> getting started -> data -> estimators ->
  power spectra -> likelihood, then API).
- Add mkdocs.yml, requirements-docs.txt and a GitHub Pages workflow
  (.github/workflows/docs.yml) triggering on main; gitignore site/.

Documentation now published at https://corentinravoux.github.io/flip/.
mkdocs build passes (non-strict; remaining warnings are pre-existing
griffe return-type-annotation style notes).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@corentinravoux @claude
docs: fix covariance-model attributions
010fdb0 
- ravouxcarreres is the Ravoux et al. (2025), arXiv:2501.16852 model
  (flip's flagship); move that attribution off ravouxnoanchor25.
- carreres23 is the recommended default model, not adamsblake20.

Updates the model __init__ docstrings, the analytical registry docstring
and the covariance-models guide table. Docstring-only; mkdocs build passes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@corentinravoux @claude
docs: cosmoprimo is the power-spectrum engine, not the Hankel backend
096f742 
Drop the stale 'Hankel backend' claim for cosmoprimo in the install
dependency table; the FFTLog/Hankel transform is flip's own (only
historically adapted from cosmoprimo, as noted in the source header).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@corentinravoux @claude
docs: document the empty_universe velocity estimator
8176438 
Cover the empty_universe estimator (eq. 4 of arXiv:1610.04677) added on
main, keeping the velocity-estimators guide in sync with the rebased code.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Copilot AI reviewed Jul 30, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Migrates the project documentation from a Sphinx/ReadTheDocs setup to a MkDocs Material site published via GitHub Pages, while also adding extensive in-code docstrings and introducing new forward-modeling “flox_like” sampling/likelihood code.

Changes:

  • Replace Sphinx/ReadTheDocs docs with MkDocs Material + mkdocstrings configuration and new Markdown docs pages.
  • Update packaging/docs dependencies (pyproject.toml extras + requirements-docs.txt) and add a GitHub Actions workflow to build/deploy docs to Pages.
  • Add/expand docstrings across many modules, and add new forward-modeling code under flip/forward/flox_like/ plus a new voxel-selection helper in the Gaussian simulation box.

Reviewed changes

Copilot reviewed 80 out of 83 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
requirements-docs.txt Add MkDocs build dependencies for CI docs builds.
README.md Update documentation badge/link and logo path for new MkDocs site.
pyproject.toml Switch docs extra from Sphinx toolchain to MkDocs toolchain.
mkdocs.yml New MkDocs Material configuration, nav, mkdocstrings plugin setup.
flip/utils.py Add/expand module and API docstrings.
flip/power_spectra/pyccl_engine.py Add module docstring.
flip/power_spectra/models.py Add module docstring.
flip/power_spectra/generator.py Add module docstring.
flip/power_spectra/cosmoprimo_engine.py Add module docstring.
flip/power_spectra/class_engine.py Add module docstring.
flip/forward/simulation/gaussian/box.py Add get_voxels_in_direction helper for LOS voxel sampling.
flip/forward/flox_like/sampler.py New sampler implementation for flox-like workflow (JAX/TFP).
flip/forward/flox_like/probabilities.py New probability/log-probability functions for flox-like workflow.
flip/forward/flox_like/likelihood.py New likelihood helpers for flox-like workflow.
flip/forward/field_utils.py Add a new radial_velocity_from_grid implementation (and keep older variant).
flip/data/load_data_test.py Add/expand loader docstrings for packaged example/test data.
flip/data_vector/snia_vectors.py Add/expand module/class/function docstrings.
flip/data_vector/mesh.py Add/expand docstrings for mesh gridding utilities.
flip/data_vector/gw_vectors.py Add/expand module/class docstrings.
flip/data_vector/galaxypv_vectors.py Add/expand module/class docstrings.
flip/data_vector/basic.py Add/expand docstrings across core data vector classes.
flip/covariance/symbolic.py Add module docstring for symbolic codegen utilities.
flip/covariance/plot_utils.py Add module docstring.
flip/covariance/likelihood.py Add/expand docstrings for likelihood classes.
flip/covariance/hankel.py Add/expand docstrings for Hankel/FFTLog code.
flip/covariance/generator.py Add module docstring.
flip/covariance/fitter.py Add/expand docstrings; update EMCEE sampler docs.
flip/covariance/fit_utils.py Add module docstring.
flip/covariance/fisher.py Add/expand docstrings.
flip/covariance/emulators/skgpmatrix.py Add module docstring.
flip/covariance/emulators/nnmatrix.py Add module/class docstrings.
flip/covariance/emulators/gpmatrix.py Add module docstring.
flip/covariance/emulators/generator.py Add module docstring and fill missing docstrings.
flip/covariance/covariance.py Add module docstring.
flip/covariance/cov_utils.py Add module docstring and docstring for compute_phi_bisector_theorem.
flip/covariance/contraction.py Add module docstring.
flip/covariance/analytical/rcrk24/init.py Add model docstring.
flip/covariance/analytical/ravouxqin26/init.py Add model docstring.
flip/covariance/analytical/ravouxnoanchor25/init.py Add model docstring.
flip/covariance/analytical/ravouxcarreres/init.py Add model docstring.
flip/covariance/analytical/lai22/generator.py Add generator docstring.
flip/covariance/analytical/lai22/init.py Add model docstring.
flip/covariance/analytical/genericzdep/init.py Add template model docstring.
flip/covariance/analytical/carreres23/generator.py Add generator docstring.
flip/covariance/analytical/carreres23/init.py Add model docstring.
flip/covariance/analytical/adamsblake20/init.py Add model docstring.
flip/covariance/analytical/adamsblake17plane/generator.py Add generator docstring.
flip/covariance/analytical/adamsblake17plane/init.py Add model docstring.
flip/covariance/analytical/adamsblake17/init.py Add model docstring.
flip/covariance/analytical/init.py Add registry module docstring.
flip/_subpackages.py Add docstrings for dependency probing helpers.
flip/_config.py Add module docstring for global JAX flag.
flip/init.py Add docstrings for lazy import hooks.
docs/velocity-estimators.md New MkDocs page replacing prior RST content.
docs/vel_estimators.rst Remove Sphinx RST velocity estimator docs.
docs/power-spectra.md New MkDocs page replacing prior RST content.
docs/power_spectra.rst Remove Sphinx RST power spectra docs.
docs/likelihoods.rst Remove Sphinx RST likelihood docs.
docs/likelihoods.md New MkDocs page for likelihood documentation.
docs/installation.rst Remove Sphinx RST installation page.
docs/installation.md New MkDocs installation page.
docs/index.rst Remove Sphinx index/toctree.
docs/index.md New MkDocs landing page with pipeline overview and examples.
docs/getting-started.md New MkDocs getting-started page with notebook links and walkthrough.
docs/fitting.md New MkDocs fitting/forecasting guide.
docs/DataVector.rst Remove Sphinx RST DataVector guide.
docs/data-vectors.md New MkDocs data vectors guide.
docs/covariance-models.md New MkDocs covariance models guide.
docs/conf.py Remove Sphinx configuration.
docs/basicusage.rst Remove Sphinx getting-started RST page.
docs/api/utils.md New mkdocstrings-driven API page for flip.utils and _subpackages.
docs/api/power_spectra.md New mkdocstrings-driven API page for power spectra modules.
docs/api/index.md New MkDocs API index page describing generated API layout.
docs/api/flip.covariance.rst Remove Sphinx automodule stub.
docs/api/data_vector.md New mkdocstrings-driven API page for data vectors.
docs/api/covariance.md New mkdocstrings-driven API page for covariance/inference modules.
docs/api/covariance-models.md New mkdocstrings-driven API page for models and emulators.
docs/_templates/module.rst Remove Sphinx AutoAPI template.
.readthedocs.yaml Remove ReadTheDocs build configuration.
.gitignore Ignore MkDocs build output (site/).
.github/workflows/docs.yml Add GitHub Pages docs build + deploy workflow using MkDocs.
Comments suppressed due to low confidence (3)

flip/forward/flox_like/probabilities.py:300

  • The use_density flag passed into get_logprob_candles() is ignored: the density-based distance term is always computed and added. This makes use_density=False ineffective.
    flip/covariance/fitter.py:511
  • EMCEESampler.__init__ contains a second standalone triple-quoted string after the super().__init__ call. That string is a no-op at runtime and can confuse readers/tools; it should be removed.
    flip/forward/flox_like/probabilities.py:398
  • get_logprob_dist_mpch() is documented/used as a log-probability, but it returns raw densities (and an exp(...) penalty) rather than log-space values. This is inconsistent with the other terms (Normal(...).log_prob) and will distort the total log-likelihood.

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

Comment thread flip/forward/flox_like/sampler.py Outdated
Comment on lines +121 to +132
box_struct = {
"pk0": self.pk,
"d2v": self.d2v,
"dist_mpch_vec": self.dist_mpch_vec,
"r1d": self.r1d,
"number_bins": self.number_bins,
"kmaxindex": self.kmaxindex,
"deltak_sampling": self.deltak_sampling,
# density sampling
"dist_mpch_los": self.dist_mpch_los,
"targets_voxel_dir": self.targets_voxel_dir,
}
Comment thread flip/forward/flox_like/probabilities.py Outdated
Comment on lines +90 to +93
redshifts = eval(f"jnp.r_[{zbins}]")
a = jcosmo.utils.z2a(redshifts)
cosmo_dist = jcosmo.background.radial_comoving_distance(cosmo=cosmo, a=a)

Comment thread flip/forward/flox_like/sampler.py Outdated
Comment on lines +1 to +4
import jax
import jax.numpy as jnp
import numpy as np
from flip.forward.flox_like import probabilities
Comment thread flip/forward/simulation/gaussian/box.py Outdated
Comment on lines +121 to +134
def get_voxels_in_direction(
self, ra, dec, dist_range=None, physical_unit=False, unique=False
):
ra = jnp.atleast_1d(ra)
dec = jnp.atleast_1d(dec)

ntrial = self.number_bins * 10
xyz = jnp.stack(
spherical_to_cartesian(
ra[:, None],
dec[:, None],
jnp.linspace(*dist_range, ntrial),
)
).T
@corentinravoux
corentinravoux force-pushed the docs/mkdocs-migration branch from b686d30 to 8176438 Compare July 30, 2026 09:21
corentinravoux and others added 4 commits July 30, 2026 15:34
@corentinravoux @claude
docs: host on Read the Docs, build with MkDocs; restore Sphinx sources
842b745 
Keep the extended MkDocs documentation as the single source, but move
hosting back to Read the Docs (off GitHub Pages) with MkDocs as the
build tool:

- Restore the original Sphinx sources from git (docs/conf.py, *.rst,
  api/, _templates/, _static/) so nothing is lost; they are preserved
  for reference and excluded from the MkDocs build via mkdocs.yml
  exclude_docs.
- Rewrite .readthedocs.yaml to compile with MkDocs (mkdocs: key) and
  install requirements-docs.txt; RTD hosts at flip.readthedocs.io.
- Remove the GitHub Pages workflow (.github/workflows/docs.yml).
- Point site_url and the README badge/link back to Read the Docs.

Pydoc docstrings from the earlier pass are unchanged. mkdocs build
passes cleanly with the Sphinx sources present but excluded.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@corentinravoux @claude
docs: revert to Sphinx source (.rst) on Read the Docs, extend to matu…
0dd4ffa 
…re subpackages

Per request, .rst is the documentation source again and Read the Docs
builds it with Sphinx (mkdocs cannot build .rst). Removes the MkDocs
setup and extends the Sphinx docs to cover all mature subpackages.

- .readthedocs.yaml back to the Sphinx build (docs/conf.py), as before.
- pyproject [docs] extra restored to the Sphinx toolchain.
- Remove mkdocs.yml, requirements-docs.txt and the Markdown pages.
- Extend/update the .rst guides to the current API and add new pages:
  installation, getting started, data vectors (all vector types),
  velocity estimators (incl. full_lcdm + empty_universe), power spectra,
  covariance models (model registry), likelihoods, fitting & forecasts;
  index toctree updated. Examples verified against the code.
- conf.py: scope autoapi to the mature subpackages (autoapi_dirs=['../flip']
  + ignore forward/comparison) so the API reference is auto-generated from
  the in-code docstrings and the build is not broken by the experimental
  forward subpackage.

Pydoc docstrings from the earlier pass are unchanged. Sphinx build passes
(exit 0); remaining warnings are pre-existing autoapi re-export notes and
pre-existing docstring RST quirks.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@corentinravoux @claude
docs: fix README logo path (docs/assets -> docs/_static)
16542e5 
The Sphinx revert removed docs/assets/; point the README logo back at
the restored docs/_static/flip_logo.webp.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@corentinravoux @claude
docs: overhaul and update the README
dd27552 
- Fix the stale requirements list (drop sympy/tensorflow; add pandas,
  astropy, mpmath, scipy>=1.12) to match pyproject; move optional deps
  to a table with what each enables.
- Add PyPI install (pip install flipcosmo), note import name flip and
  Python >= 3.10.
- Add badges (docs, PyPI version, Python versions, MIT license, DOI).
- Add a three-stage pipeline summary, a verified quick-start snippet, a
  Documentation section, an expanded citation section (papers +
  CITATION.cff + Zenodo DOI) and a License section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@corentinravoux