Fix MkDocs build warnings and CI job (#254)

Add `attr_list` extension to accommodate the width specifications of
images.

Remove unresolvable cross-references, re-create resources, or re-direct
cross-references.

Update documentation, fixing retrieval and rendering.

Streamline `create-api-reference-docs` invoke task to be more
EMMOntoPy-specific.

docs/api_reference/emmopy/emmocheck.md

@@ -1,3 +1,5 @@
 # emmocheck
 
 ::: emmopy.emmocheck
+    rendering:
+      show_bases: false

docs/tools-instructions.md

@@ -202,7 +202,7 @@ The figure below is generated with the following command:
 ontograph --root=Material --relations=all --legend emmo-inferred material.png
 ```
 
-![Graph generated with the ontograph tool.](materialstate.png)
+![Graph generated with the ontograph tool.](images/material.png)
 
 ---
 

emmopy/emmopy.py

@@ -10,7 +10,7 @@ def get_emmo(inferred: Optional[bool] = True) -> "Ontology":
 
     Args:
         inferred: Whether to import the inferred version of emmo or not.
-        Default is True.
+            Default is True.
 
     Returns:
         The loaded emmo ontology.

examples/emmodoc/important_concepts.md

@@ -38,7 +38,7 @@ A `spacetime` is valid for all reference systems (as required by the theory of r
 `matter` is used to represent a group of `elementary` in an enclosing `spacetime`.
 As illustrated in the figure, a `matter` is an `elementary` or a composition of other `matter` and `vacuum`.
 
-![Matter.](html_files/emmo-matter.png){ width=540px }
+![Matter.](figs/emmo-matter.png){ width=540px }
 
 In EMMO `matter` is always a 4D spacetime.
 This is a fundamental difference between EMMO and most other ontologies.
@@ -61,7 +61,7 @@ A `state` is matter in a particular configurational state.
 It is defined as having spatial direct parts that persist (do not change) throughout the lifetime of the `state`.
 Hence, a `state` is like a snapshot of a physical in a finite time interval.
 
-![A physical can always be decomposed into a sequence of finite `state`s.](html_files/emmo-state.png){ width=440px }
+![A physical can always be decomposed into a sequence of finite `state`s.](figs/emmo-state.png){ width=440px }
 
 The use of spatial direct parthood in the definition of `state` means that a `state` cannot overlap in space with another `state`.
 
@@ -77,18 +77,18 @@ An `elementary` can still be decomposed in temporal parts, that are themselves `
 
 Example of elementaries are electrons, photons and quarks.
 
-![Elementary.](html_files/emmo-elementary.png){ width=320px }
+![Elementary.](figs/emmo-elementary.png){ width=320px }
 
 ### Granularity - direct parthood
 
 Granularity is a central concept of EMMO, which allows the user to percieve the world at different levels of detail (granularity) that follow physics and materials science perspectives.
 
-![Different levels of granularity.](html_files/emmo-granularity2.png){ width=660px }
+![Different levels of granularity.](figs/emmo-granularity2.png){ width=660px }
 
 Every material in EMMO is placed on a granularity level and the ontology gives information about the direct upper and direct lower level classes.
 This is done with the non-transitive `is_direct_part_of` relation.
 
-![Direct parthood.](html_files/emmo-direct_part.png){ width=220px }
+![Direct parthood.](figs/emmo-direct_part.png){ width=220px }
 
 Granularity is a defined class and is useful sine a reasoner automatically can put the individuals defined by the user under a
 generic class that clearly expresses the types of its compositional parts.
@@ -118,3 +118,6 @@ Properties are abstracts that are related to a specific material entity with the
 **specific observation process**, participated by a **specific observer**, who catch the physical entity behaviour that is abstracted as a property.
 
 Properties enable us to connect a measured property to the measurement process and the measurement instrument.
+
+[RoMM]: https://publications.europa.eu/en/publication-detail/-/publication/ec1455c3-d7ca-11e6-ad7c-01aa75ed71a1
+[CWA]: https://www.cen.eu/news/workshops/Pages/WS_2016-013.aspx

examples/emmodoc/introduction.md

@@ -49,7 +49,7 @@ In EMMO, the taxonomy is a rooted directed acyclic graph (DAG).
 This is important since many classification methods relies on this property, see e.g. [Valentini (2014)][Valentini2014] and [Robison et al (2015)][Robison2015].
 Note, that EMMO is a DAG does not prevent some classes from having more than one parent.
 A `Variable` is for instance both a `Mathematical` and a `Symbol`.
-See [appendix][Appendix] for the full EMMO taxonomy.
+See appendix for the full EMMO taxonomy.
 
 ## Primitive elements in EMMO
 
@@ -357,7 +357,7 @@ The EMMO ontology is structured in shells, expressed by specific ontology fragme
 
 ### Top Level
 
-The [EMMO top level](top.owl) is the group of fundamental axioms that constitute the philosophical foundation of the EMMO.
+The EMMO top level is the group of fundamental axioms that constitute the philosophical foundation of the EMMO.
 Adopting a physicalistic/nominalistic perspective, the EMMO defines real world objects as 4D objects that are always extended in space and time (i.e. real world objects cannot be spaceless nor timeless).
 For this reason abstract objects, i.e. objects that does not extend in space and time, are forbidden in the EMMO.
 
@@ -368,14 +368,14 @@ These symbols appear in actions (semiotic processes) meant to communicate meanin
 Another important building block of from analytical philosophy is atomistic mereology applied to 4D objects.
 The EMMO calls it 'quantum mereology', since the there is a epistemological limit to how fine we can resolve space and time due to the uncertanity principles.
 
-The [mereotopology](top/mereotopology.owl) module introduces the fundamental mereotopological concepts and their relations with the real world objects that they represent.
+The mereotopology module introduces the fundamental mereotopological concepts and their relations with the real world objects that they represent.
 The EMMO uses mereotopology as the ground for all the subsequent ontology modules.
 The concept of topological connection is used to define the first distinction between ontology entities namely the *Item* and *Collection* classes.
 Items are causally self-connected objects, while collections are causally disconnected.
 Quantum mereology is represented by the *Quantum* class.
 This module introduces also the fundamental mereotopological relations used to distinguish between space and time dimensions.
 
-The [physical](top/physical.owl) module, defines the *Physical* objects and the concept of *Void* that plays a fundamental role in the description of multiscale objects and quantum systems.
+The physical module, defines the *Physical* objects and the concept of *Void* that plays a fundamental role in the description of multiscale objects and quantum systems.
 It also define the *Elementary* class, that restricts mereological atomism in space.
 
 ![The EMMO top level.](figs/top.png){ width=440px }
@@ -403,7 +403,7 @@ Phenomenic objects can be used in a semiotic process as signs.
 The *Physicalistic* perspective class introduces the concept of real world objects that have a meaning for the under applied physics perspective.
 
 The *Holistic* perspective class introduces the concept of real world objects that unfold in time in a way that has a meaning for the EMMO user, through the definition of the classes *Process* and *Participant*.
-The [semiotics](top/semiotics.owl) module introduces the concepts of semiotics and the *Semiosis* process that has a *Sign*, an *Object* and an *Interpreter* as participants.
+The semiotics module introduces the concepts of semiotics and the *Semiosis* process that has a *Sign*, an *Object* and an *Interpreter* as participants.
 This forms the basis in EMMO to represent e.g. models, formal languages, theories, information and properties.
 
 ![The semiotic level, showing both the taxonomy (open black arrows) and other relations as listed in the caption. The inverted arrows corresponds to inverse relations.](figs/Semiotic.png){ width=540px }

mkdocs.yml

@@ -36,6 +36,7 @@ extra_css:
 
 markdown_extensions:
   - admonition
+  - attr_list
   - pymdownx.highlight
   - pymdownx.superfences
   - pymdownx.inlinehilite
@@ -60,15 +61,13 @@ plugins:
             show_category_heading: false
             show_if_no_docstring: false
             show_source: true
+            show_bases: true
             group_by_category: true
             heading_level: 2
           selection:
             filters:
-              - "!^_[^_]"
-              - "!__all__$"
-              - "!__str__$"
-              - "!__repr__$"
-              - "!ValidatorResults$"
+              - "!^_"
+              - "^__init__$"
             members: true
             inherited_members: false
             docstring_style: google

ontopy/utils.py

@@ -399,8 +399,8 @@ def convert_imported(input, output, input_format=None, output_format='xml',
 
     Warning:
         To convert to Turtle (`.ttl`) format, you must have installed
-        `rdflib>=6.0.0`. See [Known issues](../README.md#Known-issues) in the
-        README for more information.
+        `rdflib>=6.0.0`. See [Known issues](../../../#known-issues) for
+        more information.
 
     Args:
         input: input ontology file name
@@ -501,8 +501,8 @@ def squash_imported(input, output, input_format=None, output_format='xml',
 
     Warning:
         To convert to Turtle (`.ttl`) format, you must have installed
-        `rdflib>=6.0.0`. See [Known issues](../README.md#Known-issues) in the
-        README for more information.
+        `rdflib>=6.0.0`. See [Known issues](../../../#known-issues) for
+        more information.
 
     """
     inroot = os.path.dirname(os.path.abspath(input))

tasks.py

@@ -84,13 +84,10 @@ def write_file(full_path: Path, content: str) -> None:
     docs_api_ref_dir = TOP_DIR / "docs/api_reference"
 
     unwanted_subdirs = ("__pycache__",)
+    unwanted_files = ("__init__.py",)
 
     pages_template = 'title: "{name}"\ncollapse_single_pages: false\n'
     md_template = "# {name}\n\n::: {py_path}\n"
-    models_template = (
-        md_template
-        + f"{' ' * 4}rendering:\n{' ' * 6}show_if_no_docstring: true\n"
-    )
 
     if docs_api_ref_dir.exists() and pre_clean:
         shutil.rmtree(docs_api_ref_dir, ignore_errors=True)
@@ -130,12 +127,13 @@ def write_file(full_path: Path, content: str) -> None:
 
             # Create markdown files
             for filename in filenames:
-                if re.match(r".*\.py$", filename) is None or filename in (
-                    "__init__.py",
-                    "run.py",
+                if (
+                    re.match(r".*\.py$", filename) is None
+                    or filename in unwanted_files
                 ):
                     # Not a Python file: We don't care about it!
-                    # Or filename is `__init__.py`: We don't want it!
+                    # Or filename is in the tuple of unwanted files:
+                    # We don't want it!
                     continue
 
                 basename = filename[: -len(".py")]
@@ -146,12 +144,12 @@ def write_file(full_path: Path, content: str) -> None:
                 )
                 md_filename = filename.replace(".py", ".md")
 
-                # For models we want to include EVERYTHING, even if it doesn't
-                # have a doc-string
-                template = (
-                    models_template
-                    if str(relpath) == "models" else md_template
-                )
+                # For emmopy.emmocheck we want to exclude base clases
+                template = md_template
+                if str(relpath) == "emmopy" and basename == "emmocheck":
+                    template += (
+                        f"{' ' * 4}rendering:\n{' ' * 6}show_bases: false\n"
+                    )
 
                 write_file(
                     full_path=docs_sub_dir / md_filename,