Updated docs python handler

.github/workflows/ci_workflow.yml

@@ -262,4 +262,14 @@ jobs:
         fi
 
     - name: Build check
-      run: mkdocs build --strict --verbose
+      run: |
+        mkdocs build 2>build_out.txt
+        WARNING_LINES=$( cat build_out.txt | grep WARNING | wc -l )
+        if [ ${WARNING_LINES} != 1 ]; then
+          echo -e "FAIL !\n\n"
+          cat build_out.txt
+          exit 1
+        else
+          echo -e "Only 1 warning - that's workable :)\n\n"
+          cat build_out.txt
+        fi

ontopy/excelparser.py

@@ -71,35 +71,30 @@ def create_ontology_from_excel(  # pylint: disable=too-many-arguments
             that are erroneously defined or other errors in the excel sheet.
 
     Returns:
-        A tuple with the
-        * created ontology
-        * associated catalog of ontology names and resolvable path as dict
-        * a dictionary with lists of concepts that raise errors, with the
-          following keys:
-            - "already_defined": These are concepts that are already in
-                                 the ontology,
-                                 either because they were already added in a
-                                 previous line of
-                                 the excelfile/pandas dataframe,
-                                 or because it is already defined
-                                 in the imported ontologies.
-            - "in_imported_ontologies": Concepts that are defined in the excel,
-                                 but already exist in the imported ontologies.
-                                 This is a subset of the 'already_defined'
-            - "wrongly_defined": Concepts that are given an invalid prefLabel
-                                 (e.g. with a space in the name).
-            - "missing_parents": Concepts that are missing parents.
-                                 These concepts are added directly
-                                 under owl:Thing.
-            - "invalid_parents": Concepts with invalidly defined parents.
-                                 These concepts are added directly
-                                 under owl:Thing.
-            - "nonadded_concepts": List of all concepts that are not added,
-                                 either because the prefLabel is invalid,
-                                 or because the concept has already been added
-                                 once or already exists in an imported
-                                 ontology.
-
+        A tuple with the:
+
+            * created ontology
+            * associated catalog of ontology names and resolvable path as dict
+            * a dictionary with lists of concepts that raise errors, with the
+              following keys:
+
+                - "already_defined": These are concepts that are already in the
+                    ontology, either because they were already added in a
+                    previous line of the excelfile/pandas dataframe, or because
+                    it is already defined in the imported ontologies.
+                - "in_imported_ontologies": Concepts that are defined in the
+                    excel, but already exist in the imported ontologies.
+                    This is a subset of the 'already_defined'.
+                - "wrongly_defined": Concepts that are given an invalid
+                    prefLabel (e.g. with a space in the name).
+                - "missing_parents": Concepts that are missing parents.
+                    These concepts are added directly under owl:Thing.
+                - "invalid_parents": Concepts with invalidly defined parents.
+                    These concepts are added directly under owl:Thing.
+                - "nonadded_concepts": List of all concepts that are not added,
+                    either because the prefLabel is invalid, or because the
+                    concept has already been added once or already exists in an
+                    imported ontology.
 
     """
     # Get imported ontologies from optional "Imports" sheet

ontopy/factpluspluswrapper/owlapi_interface.py

@@ -28,6 +28,7 @@ def reason(self, graph):
 
         Args:
             graph (Graph): An rdflib graph to execute the reasoner on.
+
         """
         with tempfile.NamedTemporaryFile("wt") as tmpdir:
             graph.serialize(tmpdir.name, format="xml")
@@ -37,32 +38,37 @@ def reason_files(self, *owl_files):
         """Merge the given owl and generate the inferred axioms.
 
         Args:
-            owl_files (os.path): The owl files two merge
+            *owl_files (os.path): The owl files two merge.
+
         """
         return self._run(*owl_files, command="--run-reasoner")
 
     def merge_files(self, *owl_files):
         """Merge the given owl files and its import closure.
 
         Args:
-            owl_files (os.path): The owl files two merge
+            *owl_files (os.path): The owl files two merge.
+
         """
         return self._run(*owl_files, command="--merge-only")
 
     @staticmethod
-    def _run(*owl_files, command, output_file=None, return_graph=True):
+    def _run(
+        *owl_files, command, output_file=None, return_graph=True
+    ) -> rdflib.Graph:
         """Run the FaCT++ reasoner using a java command.
 
         Args:
-            owl_files (str): Path to the owl files to load.
+            *owl_files (str): Path to the owl files to load.
             command (str): Either --run-reasoner or --merge-only
             output_file (str, optional): Where the output should be stored.
                 Defaults to None.
             return_graph (bool, optional): Whether the result should be parsed
                 and returned. Defaults to True.
 
         Returns:
-            rdflib.Graph: The reasoned result.
+            The reasoned result.
+
         """
         java_base = os.path.abspath(
             os.path.join(os.path.dirname(__file__), "java")

ontopy/ontodoc.py

@@ -12,13 +12,18 @@
 import subprocess  # nosec
 from textwrap import dedent
 from tempfile import NamedTemporaryFile, TemporaryDirectory
+from typing import TYPE_CHECKING
 
 import yaml
 import owlready2
 
 from ontopy.utils import asstring, camelsplit, get_label
 from ontopy.graph import OntoGraph, filter_classes
 
+if TYPE_CHECKING:
+    from pathlib import Path
+    from typing import Iterable, Union
+
 
 class OntoDoc:
     """A class for helping documentating ontologies.
@@ -720,20 +725,20 @@ def process_branches(self):
 
     def _make_branchfig(  # pylint: disable=too-many-arguments,too-many-locals
         self,
-        name,
-        path,
-        terminated,
-        include_leafs,
-        strict_leafs,
-        width,
-        leafs,
-        relations,
-        edgelabels,
-        rankdir,
-        legend,
-        included_namespaces,
-        included_ontologies,
-    ):
+        name: str,
+        path: "Union[Path, str]",
+        terminated: bool,
+        include_leafs: bool,
+        strict_leafs: bool,
+        width: float,
+        leafs: "Union[str, list[str]]",
+        relations: str,
+        edgelabels: str,
+        rankdir: str,
+        legend: bool,
+        included_namespaces: "Iterable[str]",
+        included_ontologies: "Iterable[str]",
+    ) -> "tuple[str, list[str], float]":
         """Help method for process_branchfig().
 
         Args:
@@ -750,10 +755,12 @@ def _make_branchfig(  # pylint: disable=too-many-arguments,too-many-locals
             legend: whether to add legend
             included_namespaces: sequence of names of namespaces to be included
             included_ontologies: sequence of names of ontologies to be included
+
         Returns:
             filepath: path to generated figure
             leafs: used list of leaf node names
             width: actual figure width
+
         """
         onto = self.ontodoc.onto
         if leafs:

ontopy/utils.py

@@ -21,7 +21,7 @@
 
 if TYPE_CHECKING:
     from packaging.version import Version, LegacyVersion
-    from typing import Union
+    from typing import Optional, Union
 
 
 # Format mappings: file extension -> rdflib format name
@@ -465,12 +465,12 @@ def _validate_installed_version(
 
 
 def convert_imported(  # pylint: disable=too-many-arguments,too-many-locals
-    input_ontology,
-    output_ontology,
-    input_format=None,
-    output_format="xml",
-    url_from_catalog=None,
-    catalog_file="catalog-v001.xml",
+    input_ontology: "Union[Path, str]",
+    output_ontology: "Union[Path, str]",
+    input_format: "Optional[str]" = None,
+    output_format: str = "xml",
+    url_from_catalog: "Optional[bool]" = None,
+    catalog_file: str = "catalog-v001.xml",
 ):
     """Convert imported ontologies.
 
@@ -490,8 +490,8 @@ def convert_imported(  # pylint: disable=too-many-arguments,too-many-locals
             `input_ontology`
         output_format: output format. The default is to infer from
             `output_ontology`
-        url_from_catalog: bool | None. Whether to read urls form catalog file.
-            If None, the catalog file will be used if it exists.
+        url_from_catalog: Whether to read urls form catalog file.
+            If False, the catalog file will be used if it exists.
         catalog_file: name of catalog file, that maps ontology IRIs to
             local file names
     """

requirements_docs.txt

@@ -3,4 +3,4 @@ mike~=1.1
 mkdocs~=1.3
 mkdocs-awesome-pages-plugin~=2.7
 mkdocs-material~=8.2
-mkdocstrings~=0.18.1
+mkdocstrings[python]~=0.18.1