Conversation
CI, launched with Python 3.10, is producing an error. We were unable to reproduce the error locally. For the time being, we have decided to launch the CI only with Python 3.12, as this error does not seem to occur with this version.
Annotation monitoring was cumulating between pangenomes rather than giving the time of the step for each one.
Removed outdated PR template and example content.
Added a review checklist template for PR validation.
Enhanced path resolution by adding the `resolve_path` function to handle both absolute and relative paths robustly. Updated `check_tsv_sanity` to utilize this function for improved error handling and path validation.
## Description This PR adds a pull request template and a saved reply template for code reviews to improve contribution workflow and maintain code quality standards across the project. ## Type of change - [x] New feature or analysis ## Related issue N/A - Process improvement ## What changed - Added `.github/pull_request_template.md` with a flexible structure for contributors - Created a saved reply template for reviewers to ensure consistent code review process - Template includes sections relevant to bioinformatics projects (datasets, scientific accuracy, reproducibility) ## Testing N/A - Process improvement ## Documentation - [x] Updated README or docs if needed Instructions for using the saved reply template are included in the PR description. ## Checklist - [x] My code follows the project style - [x] I've reviewed my own code - [x] Complex logic is commented - [x] No unnecessary files or debug code included ## Additional notes - Template will be visible on the next PR opened after this one is merged in main. **For contributors:** The PR template includes a disclaimer making it clear that it's a guide, not a strict requirement. This should encourage contributions without creating barriers. **For reviewers**: To use the saved reply template: 1. Go to **your** GitHub Settings → Saved replies 2. Click "Add a saved reply" 3. Name it (e.g., "PR Review Checklist") 4. Copy the template from the PR description 5. Use it during reviews by clicking the saved replies icon in the comment box
<!-- This template is here to help you structure your PR, but feel free to adapt it to your needs. Not all sections may be relevant for your contribution. --> ## Description This PR removes the automatic update of the version. The workflow was not working correctly and after discussion with mainteners, it seems like an unecessary add. ## Type of change - [x] Bug fix N/A - Process improvement ## What changed - The automatic update workflow of the VERSION file has been removed. ## Testing N/A - Process improvement ## Documentation N/A - Process improvement ## Checklist - [x] My code follows the project style - [x] I've reviewed my own code - [x] Complex logic is commented - [x] No unnecessary files or debug code included
<!-- This template is here to help you structure your PR, but feel free to adapt it to your needs. Not all sections may be relevant for your contribution. --> ## Description This PR add a guide to PANORAMA citation. ## What changed - The preprint is now integrate in the documentation as a badge and in the text - README include a How to cite section - A new page in user documentation detail how to cite PANORAMA and its environment ## Testing N/A - Process improvement ## Documentation N/A - Process improvement ## Checklist - [x] My code follows the project style - [x] I've reviewed my own code - [x] Complex logic is commented - [x] No unnecessary files or debug code included
…descriptions and required fields
…gers in documentation check workflow
- Enable `sphinx.ext.autosummary` in documentation configuration. - Configure auto-generation of stub pages for classes listed in `autosummary` blocks. - Add `exclude-members` to refine class documentation. - Introduce `_templates/summary.rst` to generate consistent navigation entries for API reference.
## Description
Comprehensive documentation audit and fix pass. Corrects broken CLI
examples, dead cross-references, and internal
contradictions across the docs, adds a new "Codebase Internals" section
to the developer guide,
fixes a documentation build that was failing on GitHub Actions, and
cleans up a number of stale/dead files and
Sphinx configuration issues found along the way.
No changes to `panorama/` source code or tests — this PR is docs, Sphinx
config, and CI workflow only.
## What changed
### Fixed broken/inconsistent content
- Corrected wrong CLI flags and drifted examples in the README and
`pansystems.md` (`--threads` → `--cpus`, `-s`/`--association all` →
matching the real CLI)
- Replaced stale `Black`/`Flake8` instructions in `tipsandtricks.md`
with the actual `ruff format`/`ruff check` commands the project uses
- Fixed dozens of broken internal cross-references (wrong anchors,
typo'd slugs, stale `#anchor` links across files) by enabling
`myst_heading_anchors` and converting cross-file anchor links to MyST
`{ref}` roles where needed
- Fixed a real heading-hierarchy bug in `align.md` (H1 → H3 skip) and a
wrong H1/H2 start level
- Fixed duplicate `autosectionlabel` collisions in new dev docs by
scoping the suppression narrowly instead of blanket-suppressing all
`myst.xref_missing`/`myst.header` warnings (which had been masking these
real issues)
### New "Codebase Internals" developer documentation
- Added `architecture.md`, `detection_workflow.md`,
`compare_workflow.md`, `io_layer.md`, `add_subcommand.md`
- Split the developer guide toctree into "Contributing & Guidelines" vs.
"Codebase Internals"
### Citation support
- Added downloadable `.bib` files under `docs/user/_static/citations/`
with "Download BibTeX" buttons (opening in a new tab)
- Updated README badges/citation to point at the published PLOS
Computational Biology paper
### Sphinx/docs infrastructure
- Added `sphinx-copybutton` (copy-to-clipboard on code blocks) and
`sphinx-autodoc-typehints` (replacing the long-dead, incompatible
`sphinx-autodoc-napoleon-typehints`)
- Added `sphinx.ext.autosummary` so classes (e.g. `GeneFamily`, `Model`,
`System`, `Pangenome`) get their own generated page and now appear in
the left sidebar, not just their parent module
- Added a MyST + Sphinx version line to the footer, `colon_fence`
support, and a fix for the sphinx-design "announcement" banner link
### CI / workflow
- **Fixed a documentation build failure**:
`docs/api/panorama.systems.md` referenced two `.py` files that are
gitignored (present locally, never committed); removed those sections so
`sphinx-build` no longer tries to import nonexistent modules on a fresh
checkout
- Added `.github/scripts/check_common_arguments_docs.py`, a lint that
fails CI if the duplicated common-argument tables across
`projection.md`/`association.md`/`partition.md`/`pansystems.md` drift
out of sync, wired into `check_doc.yml`
- `main.yml`/`ruff.yml` now skip on `doc/*` branches; `check_doc.yml`
gained a `pull_request` trigger scoped to `doc/*` branches only,
avoiding duplicate runs
- Consolidated documentation dependencies into `pyproject.toml`'s
`[doc]` extra only, deleted the redundant `docs/sphinx_requirements.txt`
### Cleanup
- Deleted 8 orphaned/stub developer doc pages (`workflows.md`,
`write.md`, and 6 script-doc pages already excluded from the Sphinx
build) and the confirmed-unused `docs/api/modules.md` and
`docs/_templates/summary.rst`'s old dead state
- Removed all emoji from user-facing documentation headings for a
consistent style
- Removed unused `docs/_static/css/custom.css` and two unreferenced
images
- Fixed the leaky file handle in `conf.py`'s `VERSION` read
(`open().read()` → `Path.read_text()`)
## Testing
### Test environment
- N/A — documentation, Sphinx configuration, and CI workflow changes
only; no `panorama/` source or test changes
- Validated with full clean Sphinx builds (`sphinx-build -E -a -b html .
build`) after every change
- Validated on ReadTheDoc build before merge
### Results
- Final local build: 0 warnings (down from 40 once the blanket
`myst.xref_missing`/`myst.header` suppressions were removed and every
surfaced issue was fixed individually)
- Reproduced the exact GitHub Actions failure (`Failed to import
panorama.systems.dictionary_validation_utils`/`parameter_validation_utils`)
in a clean conda env with a fresh `pip install .[doc]`, confirmed the
fix resolves it
- Dry-ran `.github/scripts/check_common_arguments_docs.py` against both
the consistent state (passes) and a deliberately introduced mismatch
(correctly fails with a clear diff)
## Documentation
- [ ] Added/updated code comments
- [ ] Added/updated docstring
- [x] Updated README or docs if needed
- [x] Added example usage (if relevant)
## Checklist
- [x] My code follows the project guidelines
- [x] Complex logic is commented
- [x] No unnecessary files or debug code included
- [x] My PR is targeting the `dev` branch
## Additional notes
<!-- Any other context, dependencies, or things reviewers should know
-->
- Two pre-existing, unrelated `[myst.duplicate_def]` warnings remain in
`compare_spots.md`/`compare_systems.md`
<!-- This template is here to help you structure your PR, but feel free to adapt it to your needs. Not all sections may be relevant for your contribution. --> ## Description Write_flat does not support to write conserved_spot anymore. This has been moved directly to the compare_spot command. This PR remove the argument from the command. ## What changed - `conserved_spot` argument is not checked anymore ## Documentation <!-- Mark the relevant option with an "x" --> - [ ] Added/updated code comments - [ ] Added/updated docstring - [ ] Updated README or docs if needed - [ ] Added example usage (if relevant) ## Checklist <!-- Mark the relevant option with an "x" --> - [x] My code follows the project guidelines - [x] Complex logic is commented - [x] No unnecessary files or debug code included - [x] My PR is targeting the `dev` branch
<!-- This template is here to help you structure your PR, but feel free to adapt it to your needs. Not all sections may be relevant for your contribution. --> ## Description The current behavior is to use the absolute path or the working directory relative path to find pangenome file. This is not the expected behavior describe in the documentation. Example: - file tree ├── pangenome1.h5 ├── pangenome2.h5 ├── pangenomes │ ├── pangenome3.h5 │ └── pangenome4.h5 └── pangenomes.tsv - pangenomes.tsv pangenome1 /home/user/absolute/path/pangenome1.h5 pangenome2 pangenome2.h5 pangenome3 pangenomes/pangenome3.h5 pangenome4 /home/user/absolute/path/pangenome4.h5 This work if panorama is executed where pangenomes.tsv exist. I add a new function to solve the path in the TSV. ## Related issue #53 ## What changed - Enhanced path resolution by adding the `resolve_path` function to handle both absolute and relative paths robustly. - Updated `check_tsv_sanity` to utilize this function for improved error handling and path validation. ## Documentation <!-- Mark the relevant option with an "x" --> - [ ] Added/updated code comments - [ ] Added/updated docstring - [ ] Updated README or docs if needed - [ ] Added example usage (if relevant) ## Checklist <!-- Mark the relevant option with an "x" --> - [ ] My code follows the project guidelines - [ ] Complex logic is commented - [ ] No unnecessary files or debug code included - [ ] My PR is targeting the `dev` branch ## Additional notes <!-- Any other context, dependencies, or things reviewers should know -->
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Release PR merging
devintomain, bringingmainfrom1.0.0up to1.0.4. This covers several bug fixes (annotation timing, path resolution, CLI argument names), a dependency floor bump forpyhmmer(0.12.0, required for compatibility with itsbytes→strAPI change), removal of unsupported/dead CLI options, a large documentation overhaul (developer guide, API reference, citation guide, quick-start), and CI workflow cleanup.What changed
pangenome.h5is found correctly regardless of where the pangenome TSV/CLI is invoked from (Fix relative path management to find pangenome.h5 file #54).compare_spots/compare_systemscommands.pyhmmer>=0.12.0inpyproject.tomlandpanorama.yml; updatedgenInput.py,macsymodel_translator.py, andhmm_search.pyto use plainstraccess on HMM/Hit/Sequence/Alignment attributes now that pyhmmer 0.12+ returnsstrinstead ofbytes(Fix CI #58).--conserved_spotsoption fromwrite_flat.py(Remove support for --conserved_spots in write_flat.py #56).resolve_pathutility, integrated intocheck_tsv_sanityfor robust pangenome path resolution.panorama/testsonly (srcinput), so it no longer lints unrelated paths like.github/scripts/.doc/*branches and fixed duplicate doc-check workflow runs..bibfiles (Add How to cite guide #55).Testing
Test environment:
PANORAMA_testdataset run as part of this release PR itself — each underlying change was tested/verified individually in its own PR (see Fix annotation monitoring #48, Fix CI error #49, Add pull request template for contributions #51, Remove the automatic bump version workflow #52, Fix relative path management to find pangenome.h5 file #54, Add How to cite guide #55, Remove support for --conserved_spots in write_flat.py #56, Doc/fix errors #57, Fix CI #58).Results:
dev.mainbefore merging.Documentation
Checklist
devbranch (this PR targetsmain, as a release merge)Additional notes
VERSIONis already at1.0.4ondev(bumped incrementally across the merged PRs); no further manual bump should be needed for this release. Anyone with an existingpanoramaconda env built beforepyhmmer>=0.12.0was pinned should recreate/update it to match the new floor.