Merge pull request #49 from brain-bican/docs

jinja documentation fixes

Author: hkir-dev

resources/annotation_template.md

@@ -1,12 +1,18 @@
+---
+title: {{annotation.cell_set_accession}}
+weight: {{annotation.weight}}
+---
 ## {{annotation.cell_label}} ({{annotation.cell_set_accession}})
 {% if 'parents' in annotation %}
 <b>Hierarchy: </b>
 {% for parent in annotation.parents %}
-[{{parent}}]({{metadata.purl_base}}{{parent|replace(":", "_")}}) >
+[{{parent}}](../{{parent|replace(":", "_")}}) >
 {% endfor %}
-[{{annotation.cell_set_accession}}]({{metadata.purl_base}}{{annotation.cell_set_accession|replace(":", "_")}})
+[{{annotation.cell_set_accession}}](../{{annotation.cell_set_accession|replace(":", "_")}})
 {% endif %}
 
+**PURL:** [{{metadata.purl_base}}{{annotation.cell_set_accession|replace(":", "_")}}]({{metadata.purl_base}}{{annotation.cell_set_accession|replace(":", "_")}})
+
 ---
 
 {% set labelset = metadata.labelsets|selectattr("name", "==", annotation.labelset) | list | first  %}
@@ -15,7 +21,7 @@
 
 {% if 'parent_cell_set_accession' in annotation %}
 {% set parent_annotation = metadata.annotations|selectattr("cell_set_accession", "==", annotation.parent_cell_set_accession) | list | first  %}
-**Parent Cell Set:** {{parent_annotation.cell_label}} ([{{annotation.parent_cell_set_accession}}]({{metadata.purl_base}}{{annotation.parent_cell_set_accession|replace(":", "_")}}))
+**Parent Cell Set:** {{parent_annotation.cell_label}} ([{{annotation.parent_cell_set_accession}}](../{{annotation.parent_cell_set_accession|replace(":", "_")}}))
 {% else %}
 **Parent Cell Set:** -
 {% endif %}
@@ -43,7 +49,7 @@
 | Rationale DOIs |
 |----------------|
 {% for doi in annotation.rationale_dois %}
-|{{doi}}|
+|[{{doi}}]({{doi}})|
 {% endfor %}
 {% endif %}
 
@@ -69,7 +75,7 @@
 | Transferred cell label | Source taxonomy | Source node accession | Algorithm name | Comment |
 |------------------------|-----------------|-----------------------|----------------|---------|
 {% for at in annotation.transferred_annotations %}
-|{{at.transferred_cell_label}}|{{at.source_taxonomy}}|[{{at.source_node_accession}}]({{at.purl_base}}{{at.source_node_accession|replace(":", "_")}})|{{at.algorithm_name}}|{{at.comment}}|
+|{{at.transferred_cell_label}}|[{{at.source_taxonomy}}]({{at.purl_base}})|[{{at.source_node_accession}}]({{at.purl_base}}{{at.source_node_accession|replace(":", "_")}})|{{at.algorithm_name}}|{{at.comment}}|
 {% endfor %}
 {% endif %}
 

resources/taxonomy_template.md

@@ -1,3 +1,6 @@
+---
+weight: -10
+---
 ## {{cas.title}}
 
 {{cas.description}}
@@ -20,6 +23,8 @@
 
 ---
 
+**Taxonomy PURL:** [{{cas.purl_base}}]({{cas.purl_base}})
+
 **Cell Annotation Schema Version:** {{cas.cellannotation_schema_version}}
 
 **Cell Annotation Timestamp:** {{cas.cellannotation_timestamp}}

setup.py

@@ -8,7 +8,7 @@
 
 setup(
     name="tdta",
-    version="0.1.0.dev18",
+    version="0.1.0.dev20",
     description="The aim of this project is to provide taxonomy development tools custom actions.",
     long_description=README,
     long_description_content_type="text/markdown",

src/tdta/documentation.py

@@ -22,32 +22,38 @@ def generate_documentation(sqlite_db: str, output_folder: str, project_config=No
     if not os.path.exists(output_folder):
         os.makedirs(output_folder)
 
+    cell_sets_folder = os.path.join(output_folder, "cell_sets")
+    if not os.path.exists(cell_sets_folder):
+        os.makedirs(cell_sets_folder)
+
     cas_obj = db_to_cas(sqlite_db)
     cas = cas_obj.to_dict()
     if project_config is None:
         project_config = read_project_config(Path(output_folder).parent.absolute())
     cas = transform_cas(cas, project_config)
 
     annotation_template = read_jinja_template(ANNOTATIONS_TEMPLATE)
+    cell_sets_folder = os.path.join(output_folder, "cell_sets")
     for annotation in cas["annotations"]:
         rendered_file = annotation_template.render(annotation=annotation, metadata=cas)
         annotation_file_name = annotation["cell_set_accession"].replace(":", "_")
 
-        with open(os.path.join(output_folder,  annotation_file_name + ".md"), "w") as fh:
+        with open(os.path.join(cell_sets_folder,  annotation_file_name + ".md"), "w") as fh:
             fh.write(rendered_file)
 
     taxonomy_template = read_jinja_template(TAXONOMY_TEMPLATE)
     rendered_file = taxonomy_template.render(cas=cas)
-    with open(os.path.join(output_folder, "taxonomy.md"), "w") as fh:
+    with open(os.path.join(output_folder, "index.md"), "w") as fh:
         fh.write(rendered_file)
 
 
 def transform_cas(cas, project_config):
     """
     Adds extra data to cas for visualisation purposes.
     """
-    add_purl(cas, project_config["id"])
+    add_purl(cas, project_config)
     add_parents(cas)
+    add_weigth(cas)
     transform_annotation_transfer(cas)
 
     return cas
@@ -60,22 +66,47 @@ def transform_annotation_transfer(cas):
                 parsed_url = urlparse(transferred_annotation["source_taxonomy"])
                 path_parts = parsed_url.path.split('/')
                 taxonomy_id = path_parts[-2]
-                purl_base = f"{parsed_url.scheme}://{parsed_url.netloc}/taxonomy/{taxonomy_id}#"
+                purl_base = f"{parsed_url.scheme}://{parsed_url.netloc}/taxonomy/{taxonomy_id}/"
                 transferred_annotation["purl_base"] = purl_base
 
 
-def add_purl(cas, project_id):
-    cas["purl_base"] = f"https://purl.brain-bican.org/taxonomy/{project_id}#"
+def add_purl(cas, project_config):
+    project_id = project_config["id"]
+    purl_base = get_project_purl(project_config)
+    cas["purl_base"] = purl_base
     if "cellannotation_url" not in cas:
         cas["cellannotation_url"] = f"https://purl.brain-bican.org/taxonomy/{project_id}/{project_id}.json"
 
 
+def get_project_purl(project_config):
+    if "custom_purl" in project_config:
+        purl_base = project_config["custom_purl"]
+        if not purl_base.endswith("/"):
+            purl_base += "/"
+    else:
+        project_id = project_config["id"]
+        purl_base = f"https://purl.brain-bican.org/taxonomy/{project_id}/"
+    return purl_base
+
+
 def add_parents(cas):
     parents = build_hierarchy(cas["annotations"])
     for annotation in cas["annotations"]:
         annotation["parents"] = parents[annotation["cell_set_accession"]]
 
 
+def add_weigth(cas):
+    """
+    Add weight to annotations to be used for sorting pages.
+    """
+    for annotation in cas["annotations"]:
+        order = annotation["cell_set_accession"].replace(":", "_").split("_")[-1]
+        if order.isdigit():
+            annotation["weight"] = int(order)
+        else:
+            annotation["weight"] = 10 - len(annotation["parents"])
+
+
 def build_hierarchy(annotations):
     """
     Build a hierarchy of cell sets. Keys of the dicts are cell set accessions, values are lists of parent cell set

src/test/generate_docs_test.py

@@ -17,11 +17,10 @@ def setUp(self):
             shutil.rmtree(TEST_OUTPUT)
 
     def test_documentation_generation(self):
-        generate_documentation(TEST_DB, TEST_OUTPUT, project_config={"id": "CS202210140"})
+        generate_documentation(TEST_DB, TEST_OUTPUT, project_config={"id": "CS202210140",
+                                                                     "custom_purl": "https://purl.brain-bican.org/taxonomy/CS202210140/CS202210140_non-neuronal/"})
         self.assertTrue(os.path.exists(TEST_OUTPUT))
 
-        self.assertEqual(True, False)  # add assertion here
-
     def test_hierarchy_breadcrumb(self):
         with open("./test_data/CS202210140.json") as f:
             siletti = json.load(f)