Updates on our documentation to fix a few minor issues and add new features

docs/gen_ref_pages.py

@@ -19,28 +19,48 @@
 
 import mkdocs_gen_files
 
+
 nav = mkdocs_gen_files.Nav()
 
-for path in sorted(Path("src").rglob("*.py")):
-    module_path = path.with_suffix("")
-    doc_path = path.relative_to("src").with_suffix(".md")
-    full_doc_path = Path("reference", doc_path)
+root = Path("src/python/ensembl/brc4")
+for path in sorted(root.rglob("*.py")):
+    # Drop "src/python" from the path components
+    parts = path.parts[2:]
+
+    if parts[-1] == "__main__.py":
+        continue
 
-    parts = tuple(module_path.parts)
+    doc_path = path.relative_to(root).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
 
-    if parts[-1] == "__init__":
+    if parts[-1] == "__init__.py":
         parts = parts[:-1]
         doc_path = doc_path.with_name("index.md")
         full_doc_path = full_doc_path.with_name("index.md")
-    elif parts[-1] == "__main__":
-        continue
 
     nav[parts] = doc_path.as_posix()
 
     with mkdocs_gen_files.open(full_doc_path, "w") as fd:
-        identifier = ".".join(parts)
-        print("::: " + identifier, file=fd)
+        identifier = ".".join(parts).replace(".py", "")
+        fd.write(f"::: {identifier}\n")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, Path("../") / path)
 
+root = Path("src/python/ensembl/io")
+for path in sorted(root.rglob("__init__.py")):
+    # Get the relative module path
+    module_path = path.relative_to(root).parent
+    doc_path = module_path.with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+    # Drop "src/python" and "__init__.py" from the path components
+    parts = path.parts[2:-1]
+    # Add markdown file path with its index tree
+    nav[parts] = doc_path.as_posix()
+    # Populate the markdown file with the doc stub of this Python module
+    with mkdocs_gen_files.open(full_doc_path, "a") as fd:
+        identifier = ".".join(parts)
+        fd.write(f"::: {identifier}\n")
+    # Correct the path
     mkdocs_gen_files.set_edit_path(full_doc_path, Path("../") / path)
 
 with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:

docs/index.md

@@ -28,9 +28,11 @@ Nextflow pipelines
 1. __Additional seq prepare__: BRC/Ensembl metazoa pipeline. Preparation of genome data loading files for new sequence(s) to existing species databases.  
 2. __Genome Prepare__: BRC/Ensembl metazoa pipeline. Retrieve data for genome(s), obtained from INSDC and RefSeq, validate and prepare GFF3, FASTA, JSON files for each genome accession.
 
+## License
+Software as part of [Ensembl GenomIO](https://github.com/Ensembl/ensembl-genomio) is distributed under the [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.txt).
 
 ## Project layout
-	src/ensembl/
+	src/python/ensembl/
 	├── brc4
 	│   └── runnable
 	│       ├── compare_fasta.py
@@ -89,6 +91,3 @@ Nextflow pipelines
 	        └── utils
 	            ├── archive_utils.py
 	            └── json_utils.py
-
-## License 
-Software as part of [Ensembl GenomIO](https://github.com/Ensembl/ensembl-genomio) is distributed under the [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.txt).

mkdocs.yml

@@ -20,6 +20,26 @@ copyright: Copyright © [2016-2023] EMBL-European Bioinformatics Institute
 
 theme:
   name: "material"
+  logo: img/ebang.png
+  icon:
+    repo: fontawesome/brands/github
+  palette:
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: fontawesome/solid/lightbulb
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: fontawesome/regular/lightbulb
+        name: Switch to light mode
+
+markdown_extensions:
+  - toc:
+      permalink: true
 
 plugins:
 - search
@@ -35,7 +55,12 @@ plugins:
     handlers:
       python:
         options:
+          inherited_members: true
+          members: true
+          show_root_heading: true
           show_source: true
+          show_symbol_type_heading: true
+          show_symbol_type_toc: true
 
 nav:
   - Home: index.md
@@ -44,4 +69,3 @@ nav:
   - Code Reference: reference/
   - Running Nextflow: nextflow.md
   - Ensembl-Genomio Pipelines: pipelines.md
-  - License: license.md

src/python/ensembl/io/genomio/database/factory.py

@@ -17,6 +17,8 @@
 Can be imported as a module and called as a script as well, with the same parameters and expected outcome.
 """
 
+__all__ = ["format_db_data", "get_metadata_value"]
+
 import json
 from typing import Dict, List, Optional
 

src/python/ensembl/io/genomio/events/dump.py

@@ -14,6 +14,16 @@
 # limitations under the License.
 """Module to dump stable id events from an Ensembl Core database"""
 
+__all__ = [
+    "IdsSet",
+    "DictToIdsSet",
+    "BRC4_START_DATE",
+    "Pair",
+    "UnsupportedEvent",
+    "StableIdEvent",
+    "DumpStableIDs",
+]
+
 from datetime import datetime
 from pathlib import Path
 from typing import List, Dict, Optional, Set, Tuple

src/python/ensembl/io/genomio/events/load.py

@@ -17,6 +17,8 @@
 cf the load_events functions for the events tab file format.
 """
 
+__all__ = ["IdEvent", "MapSession", "EventCollection"]
+
 from dataclasses import dataclass
 from os import PathLike
 from pathlib import Path

src/python/ensembl/io/genomio/manifest/check_integrity.py

@@ -16,6 +16,8 @@
 to ensure their contents are in sync.
 """
 
+__all__ = ["InvalidIntegrityError", "Manifest", "IntegrityTool"]
+
 import hashlib
 import logging
 import json

src/python/ensembl/io/genomio/manifest/generate.py

@@ -14,6 +14,8 @@
 # limitations under the License.
 """Creates a manifest file in a folder depending on the file names ends."""
 
+__all__ = ["ManifestMaker"]
+
 import hashlib
 import json
 from pathlib import Path

src/python/ensembl/io/genomio/seq_region/dump.py

@@ -14,6 +14,17 @@
 # limitations under the License.
 """Fetch all the sequence regions from a core database and print them in JSON format."""
 
+__all__ = [
+    "MapFormatError",
+    "get_external_db_map",
+    "get_coord_systems",
+    "get_seq_regions",
+    "add_attribs",
+    "get_synonyms",
+    "get_attribs",
+    "get_karyotype",
+]
+
 import json
 from pathlib import Path
 from typing import Any, Dict, List
@@ -26,9 +37,9 @@
 from ensembl.utils.argparse import ArgumentParser
 
 
-ROOT_DIR = Path(__file__).parent / "../../../../../.."
-DEFAULT_MAP = ROOT_DIR / "config/external_db_map/default.txt"
-KARYOTYPE_STRUCTURE = {"TEL": "telomere", "ACEN": "centromere"}
+_ROOT_DIR = Path(__file__).parent / "../../../../../.."
+_DEFAULT_MAP = _ROOT_DIR / "config/external_db_map/default.txt"
+_KARYOTYPE_STRUCTURE = {"TEL": "telomere", "ACEN": "centromere"}
 
 
 class MapFormatError(Exception):
@@ -221,7 +232,7 @@ def get_karyotype(seq_region: SeqRegion) -> List:
                 kar["name"] = band.band
             if band.stain:
                 kar["stain"] = band.stain
-                structure = KARYOTYPE_STRUCTURE.get(band.stain, "")
+                structure = _KARYOTYPE_STRUCTURE.get(band.stain, "")
                 if structure:
                     kar["structure"] = structure
             kars.append(kar)
@@ -237,7 +248,7 @@ def main() -> None:
     )
     parser.add_server_arguments(include_database=True)
     parser.add_argument_src_path(
-        "--external_db_map", default=DEFAULT_MAP.resolve(), help="File with external_db mapping"
+        "--external_db_map", default=_DEFAULT_MAP.resolve(), help="File with external_db mapping"
     )
     args = parser.parse_args()