Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
94fb375
add first draft of command line ref doc and refactor main.py
JeanMainguy Aug 13, 2026
f5c7613
apply balck
JeanMainguy Aug 13, 2026
d112fac
commit missing script
JeanMainguy Aug 13, 2026
3d51919
add description in command subparser instead in a big string in main …
JeanMainguy Aug 13, 2026
68dd932
apply black and fix minor stuffs
JeanMainguy Aug 13, 2026
15ed25a
fix group of param per command
JeanMainguy Aug 13, 2026
bb9ff66
update python version in doc CI
JeanMainguy Aug 13, 2026
ba27d1e
fix param format
JeanMainguy Aug 13, 2026
844e2b6
fix config file type
JeanMainguy Aug 13, 2026
28a1500
mv ref from top to bottom of user doc
JeanMainguy Aug 13, 2026
870cfc4
ensure python 3.9 compatibility using bokeh < 3.4 and remove | types
JeanMainguy Aug 14, 2026
e01a29e
Merge pull request #386 from labgem/add_cmd_ref_doc
JeanMainguy Aug 14, 2026
e6a5437
fix gexf namespace so the pangenome graph can be parsed
ggautreau Aug 18, 2026
3f22c30
check that written gexf files can be parsed back
ggautreau Aug 18, 2026
e23b094
open the pangenome read-only when only reading it
ggautreau Aug 18, 2026
bf8eb6f
check that info and metrics work on a read-only pangenome
ggautreau Aug 18, 2026
1688aad
Merge branch 'master' into dev
JeanMainguy Aug 20, 2026
d161c66
Refactor command line documentation and improve RGP clustering detail…
jpjarnoux Aug 20, 2026
b50e56f
Fix GEXF namespace so the pangenome graph can be parsed (#388)
JeanMainguy Aug 20, 2026
1c49a67
Merge pull request #389 from labgem/fix/read-only-pangenome
JeanMainguy Aug 20, 2026
8f2ec4d
add external link to example input
JeanMainguy Aug 25, 2026
df25055
fix link
JeanMainguy Aug 25, 2026
9343903
fix md links in whats new in v2
JeanMainguy Aug 25, 2026
94dae76
Merge pull request #393 from labgem/doc/add_input_example
axbazin Aug 26, 2026
2bb1cc0
Support Python 3.10–3.13 and drop Python 3.9 (#399)
JeanMainguy Sep 16, 2026
0fc7274
Merge remote-tracking branch 'origin/master' into dev
JeanMainguy Sep 17, 2026
4f5a0b0
add default in help text (#396)
JeanMainguy Sep 18, 2026
e7c3ef5
normalize cli help with copilot (#395)
JeanMainguy Sep 18, 2026
b3d4c0c
Replace custom GenBank parsing with gb-io (#397)
mnsoln Sep 22, 2026
dd0f0bb
fix: replace aragorn subprocess with pyaragorn (#401) (#402)
fathirramadhan-web Sep 22, 2026
d78b828
Improve parsing and error handling for malformed genome/file-path an…
JeanMainguy Sep 23, 2026
191f489
improve wording around TSV file (#406)
JeanMainguy Sep 23, 2026
7a153b7
Regenerate and commit the generated command reference when CLI change…
JeanMainguy Sep 23, 2026
353c335
Partition reproducibility (#408)
rsiminel Sep 28, 2026
77c8e5e
Refactor and optimize RGP clustering (#392)
JeanMainguy Sep 28, 2026
f57c4d2
Merge branch 'master' into dev
JeanMainguy Sep 28, 2026
85c7f9d
Release 2.3.2
github-actions[bot] Sep 28, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 61 additions & 3 deletions .github/workflows/check_doc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,83 @@ on:
- 'docs/**'
- '.readthedocs.yaml'
- '.github/workflows/check_doc.yml'
- 'ppanggolin/**'
- 'setup.py'
- 'pyproject.toml'

permissions:
contents: write

jobs:
build:
generate-command-reference:
if: >-
github.event_name == 'push' && (
contains(github.event.head_commit.modified, 'ppanggolin/') ||
contains(github.event.head_commit.modified, 'setup.py') ||
contains(github.event.head_commit.modified, 'pyproject.toml') ||
contains(github.event.head_commit.added, 'ppanggolin/') ||
contains(github.event.head_commit.added, 'setup.py') ||
contains(github.event.head_commit.added, 'pyproject.toml')
)
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0

- uses: actions/setup-python@v5
with:
python-version: '3.12'

- name: install ppanggolin with python deps and doc deps
run: pip install .[doc]

- name: regenerate command reference from CLI
run: python docs/_scripts/generate_command_reference.py

- name: commit generated docs if changed
env:
GITHUB_REF_NAME: ${{ github.ref_name }}
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
if [[ -n "$(git status --porcelain -- docs/user/command_reference.md)" ]]; then
git add docs/user/command_reference.md
git commit -m "docs: regenerate command reference"
git push origin HEAD:${GITHUB_REF_NAME}
fi

build-docs:
if: >-
github.event_name == 'push' && (
contains(github.event.head_commit.modified, 'docs/') ||
contains(github.event.head_commit.modified, '.readthedocs.yaml') ||
contains(github.event.head_commit.modified, '.github/workflows/check_doc.yml') ||
contains(github.event.head_commit.added, 'docs/') ||
contains(github.event.head_commit.added, '.readthedocs.yaml') ||
contains(github.event.head_commit.added, '.github/workflows/check_doc.yml')
)
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0

- uses: actions/setup-python@v5
with:
python-version: '3.9'
python-version: '3.12'

- name: install ppanggolin with python deps and doc deps
run: pip install .[doc]

- name: Complete workflow
- name: Build documentation
shell: bash -l {0}
run: |
cd docs/
sphinx-build -b html . build/

# Great extra actions to compose with:
# Create an artifact of the html output.
- uses: actions/upload-artifact@v4
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/check_recipes.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ jobs:
strategy:
matrix:
os: ['ubuntu-latest','macos-latest']
python-version: ['3.9','3.10', '3.11', '3.12']
python-version: ['3.10', '3.11', '3.12', '3.13']
# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ jobs:
strategy:
matrix:
os: ['ubuntu-latest', 'macos-latest']
python-version: ['3.9', '3.12']
python-version: ['3.10', '3.13']
defaults:
run:
shell: conda run --no-capture-output -n ppanggolin bash -e {0}
Expand Down Expand Up @@ -108,4 +108,4 @@ jobs:
name: comparison-results_${{ matrix.os }}_python${{ matrix.python-version }}
path: testingDataset/info_to_test/*



2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ By default, it uses parameters that we have found to be generally the best for w

### Input files

The file `GENOMES_FASTA_LIST` is a tsv-separated file with the following organization :
The file `GENOMES_FASTA_LIST` is a tab separated values (TSV) file with the following organization:

1. The first column contains a unique genome name **(without space)**
2. The second column contains the path to the associated FASTA file
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
2.3.1
2.3.2
253 changes: 253 additions & 0 deletions docs/_scripts/generate_command_reference.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,253 @@
#!/usr/bin/env python3

import argparse
import re
import sys
from pathlib import Path
from typing import Iterable, List, Optional, Union

REPO_ROOT = Path(__file__).resolve().parents[2]
if str(REPO_ROOT) not in sys.path:
sys.path.insert(0, str(REPO_ROOT))

from ppanggolin.main import build_parser


def _format_type(action: argparse.Action) -> str:
if action.option_strings and action.nargs == 0:
return "bool"

if isinstance(action.type, type):
return action.type.__name__

if action.type is not None:
type_name = getattr(action.type, "__name__", None)
if type_name in {"check_log", "restricted_float", "min_one", "filter_values"}:
return {
"check_log": "str",
"restricted_float": "float",
"min_one": "int",
"filter_values": "str",
}[type_name]
if type_name:
return type_name
if hasattr(action.type, "__call__"):
return "str"

if action.default is not None:
if isinstance(action.default, bool):
return "bool"
return type(action.default).__name__

if action.const is not None:
return type(action.const).__name__

return "str"


def _format_default(action: argparse.Action) -> str:

if action.default is None:
return "—"
if action.default is False and action.option_strings:
return "False"
if action.default is True and action.option_strings:
return "True"

value = str(action.default)
pattern = (
r"^(?P<prefix>.*?)(?:_?DATE\d{4}-\d{2}-\d{2}_HOUR\d{2}\.\d{2}\.\d{2}_PID\d+)$"
)
match = re.match(pattern, value)
if match:
prefix = match.group("prefix").rstrip("_")
return f"`{prefix}_<date>_<pid>`"

if isinstance(action.default, Path):
return f"`{action.default}`"
if isinstance(action.default, (list, tuple, set)):
return f"`{str(list(action.default))}`"
if isinstance(action.default, str):
return f"`{action.default}`"
return str(action.default)


def _format_choices(action: argparse.Action) -> str:
if not action.choices:
return "—"
return ", ".join(f"`{choice}`" for choice in action.choices)


def _format_param_name(action: argparse.Action) -> str:
names = [opt for opt in action.option_strings]
if not names:
if action.metavar:
return action.metavar
return action.dest
return ", ".join(names)


def _describe_action(action: argparse.Action) -> dict:
return {
"name": _format_param_name(action),
"type": _format_type(action),
"default": _format_default(action),
"required": "Yes" if action.required else "No",
"choices": _format_choices(action),
"help": (action.help or "").replace("\n", " ").strip(),
"is_flag": action.option_strings and action.nargs == 0,
}


def _iter_action_groups(
parser: argparse.ArgumentParser,
) -> Iterable[tuple[str, list[argparse.Action]]]:
seen = set()
for action_group in parser._action_groups:
group_title = action_group.title or "Arguments"
if group_title in {"positional arguments", "options"}:
continue

actions = []
for action in action_group._group_actions:
if action.dest == "help":
continue
if action.dest in seen:
continue
seen.add(action.dest)
actions.append(action)

if actions:
yield group_title, actions


def _generate_action_table(
title: str, actions: list[argparse.Action], command_name: Optional[str] = None
) -> list[str]:
heading = (
title if command_name is None else f"{title} for ppanggolin {command_name}"
)
lines = [
f"#### {heading}",
"",
"| Parameter | Type | Default | Description |",
"|---|---|---|---|",
]

for action in actions:
info = _describe_action(action)
description_parts = []
help_text = info["help"].strip() if info["help"] else "—"
description_parts.append(help_text)

if info["required"] == "Yes":
description_parts.append("Required: Yes")
if info["choices"] != "—":
description_parts.append(f"<br>Choices: {info['choices']}")

description = " ".join(part for part in description_parts if part)
lines.append(
f"| `{info['name']}` | {info['type']} | {info['default']} | {description} |"
)

return lines


def _generate_command_section(
command_name: str, parser: argparse.ArgumentParser
) -> str:
title = f"### `ppanggolin {command_name}`"
description = (
getattr(parser, "description", None)
or "Command description is not explicitly set in this parser."
)
lines = [
title,
"",
description.strip(),
"",
]

action_groups = list(_iter_action_groups(parser))
if not action_groups:
lines.append("No parameters are defined for this command.")
return "\n".join(lines) + "\n"

for group_title, actions in action_groups:
lines.extend(_generate_action_table(group_title, actions, command_name))
lines.append("")

return "\n".join(lines).rstrip() + "\n"


def _collect_subcommands(
parser: argparse.ArgumentParser,
) -> List[tuple[str, argparse.ArgumentParser]]:
subparsers_action = next(
(
group
for group in parser._action_groups
if isinstance(group, argparse._ArgumentGroup)
),
None,
)
subparsers = []
for action in getattr(parser, "_actions", []):
if isinstance(action, argparse._SubParsersAction):
subparsers = action.choices.items()
break

commands = []
for command_name, command_parser in subparsers:
commands.append((command_name, command_parser))
commands.sort(key=lambda item: item[0])
return commands


def generate_reference(output_path: Optional[Union[Path, str]] = None) -> str:
parser = build_parser()
commands = _collect_subcommands(parser)

sections = [
"# Command-line reference",
"",
"Complete reference of the PPanGGOLiN command-line interface.",
"",
"This page is automatically generated from the PPanGGOLiN command-line parser.",
"",
]

category_order = [
"Basic",
"Expert",
"Output",
"Regions of Genomic Plasticity",
"Analysis using reference pangenomes",
"Utility command",
]
grouped_commands: dict[str, List[tuple[str, argparse.ArgumentParser]]] = {}
for command_name, command_parser in commands:
category = getattr(command_parser, "category", "General")
grouped_commands.setdefault(category, []).append((command_name, command_parser))

for category in category_order:
if category not in grouped_commands:
continue
sections.append(f"## {category}")
sections.append("")
for command_name, command_parser in grouped_commands[category]:
sections.append(_generate_command_section(command_name, command_parser))
sections.append("")

rendered = "\n".join(sections).strip() + "\n"

if output_path is not None:
output_file = Path(output_path)
output_file.parent.mkdir(parents=True, exist_ok=True)
output_file.write_text(rendered, encoding="utf-8")
return rendered


if __name__ == "__main__":
script_path = Path(__file__).resolve().parents[1] / "user" / "command_reference.md"
generate_reference(script_path)
Loading
Loading