Merge pull request #24 from haddocking/more-releas-prep

Add docs/cli.md

Author: sverhoeven

.gitignore

@@ -73,3 +73,4 @@ IDEAS.md
 /docs/alphafold_files/
 /docs/pdb_files/
 /docs/density_filtered/
+/docs/cli.md

docs/hooks.py

@@ -0,0 +1,70 @@
+"""MkDocs hooks for generating CLI documentation."""
+
+import argparse
+import io
+import logging
+from pathlib import Path
+
+from protein_detective.cli import make_parser
+
+logger = logging.getLogger("mkdocs.plugins.argparse")
+
+
+def generate_cli_docs() -> str:
+    """Generate CLI documentation markdown."""
+    parser = make_parser()
+
+    # Capture main help
+    help_output = io.StringIO()
+    parser.print_help(help_output)
+    main_help = help_output.getvalue()
+
+    # Start building markdown
+    markdown_lines = [
+        "# CLI Reference\n",
+        "Documentation for the `protein-detective` CLI commands.\n",
+        "## Main Command\n",
+        "```shell",
+        "protein-detective --help",
+        main_help,
+        "```\n## Subcommands\n",
+    ]
+
+    # Get subcommands and their help
+    subparsers_actions = [action for action in parser._actions if isinstance(action, argparse._SubParsersAction)]
+
+    if subparsers_actions:
+        subparsers_action = subparsers_actions[0]
+        for sub_command, subparser in subparsers_action.choices.items():
+            # Capture subcommand help
+            help_output = io.StringIO()
+            subparser.print_help(help_output)
+            subcommand_help = help_output.getvalue()
+
+            markdown_lines.extend(
+                [
+                    f"### {sub_command}\n",
+                    "```shell",
+                    f"$ protein-detective {sub_command} --help",
+                    subcommand_help,
+                    "```\n",
+                ]
+            )
+
+    return "\n".join(markdown_lines)
+
+
+def on_pre_build(**_kwargs):
+    """Generate CLI documentation before building the docs."""
+    docs_content = generate_cli_docs()
+
+    # Check if content has changed before writing
+    docs_dir = Path(__file__).parent
+    cli_md_path = docs_dir / "cli.md"
+
+    # Only write if content is different to avoid rebuild loops
+    if not cli_md_path.exists() or cli_md_path.read_text() != docs_content:
+        cli_md_path.write_text(docs_content)
+        logger.info("CLI documentation generated/updated successfully")
+    else:
+        logger.info("CLI documentation unchanged, skipping write")

mkdocs.yml

@@ -2,6 +2,10 @@ site_name: Protein Detective
 site_url: https://bonvinlab.org/protein_detective
 repo_url: https://github.com/haddocking/protein-detective
 watch: [mkdocs.yml, README.md, src/protein_detective]
+exclude_docs: |
+  hooks.py
+hooks:
+  - docs/hooks.py
 theme: 
   name: mkdocs
   color_mode: auto
@@ -33,6 +37,7 @@ markdown_extensions:
 
 nav:
   - Home: index.md
+  - CLI Reference: cli.md
   - Notebooks:
     - Retrieve: uniprot.ipynb
     - AlphaFold: alphafold.ipynb

src/protein_detective/cli.py

@@ -132,13 +132,18 @@ def handle_prune_pdbs(args):
     print(f"Written {nr_files} PDB files to {single_chain_dir} directory.")
 
 
-def main():
-    parser = argparse.ArgumentParser(description="Protein Detective CLI")
+def make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Protein Detective CLI", prog="protein-detective")
     subparsers = parser.add_subparsers(dest="command", required=True)
     add_search_parser(subparsers)
     add_retrieve_parser(subparsers)
     add_density_filter_parser(subparsers)
     add_prune_pdbs_parser(subparsers)
+    return parser
+
+
+def main():
+    parser = make_parser()
 
     args = parser.parse_args()
 

src/protein_detective/workflow.py

@@ -1,3 +1,5 @@
+"""Workflow steps"""
+
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Literal