docs(domain): Add diagram of entities for each domain context

Abstract
========

In the specifications part of the documentation, on each context, add
a diagram representing all entities with their relations

Motivation
==========

Having a "big picture" of each domain context is a great addition to
the detailed specifications.

It's important for such things to be generated from the code, to avoid
the classical problem of out of sync documentation.

Rationale
=========

There are many steps:

- import all python files to get all the subclasses of `BaseModel`,
  thanks to `pkgutil.wal_packages` and `importlib.import_module`
- iterate over all the subclasses of `BaseModel` to get the final ones,
  ie the ones without any subclasses
- find all contexts, assuming all contexts are directly at the root of
  the `isshub.domain.contexts` package, thanks to
  `pgkutil.iter_modules`
- introspect model fields thanks to `typing.get_type_hints` and the
  `metadata` attribute of `attr` to get the name of relations (in
  python 3.9 we'll be able to use the `Annotated` type for that)
- manually create `.dot` files
- in the doc building process, create all these dot files and use
  the `graphviz` sphinx plugin to automatically render the diagrams
- insert the diagrams at the top of each context specification index
  page

docs/conf.py

@@ -12,11 +12,10 @@
 #
 
 
-import glob
-import importlib
 import os
 import subprocess
 import sys
+from glob import glob
 
 from sphinx.ext import apidoc
 
@@ -45,6 +44,7 @@
     "sphinx.ext.doctest",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx.ext.graphviz",
     "sphinx_autodoc_typehints",
     "sphinxprettysearchresults",
 ]
@@ -144,6 +144,24 @@ def run_gherkindoc(_):
         ]
     )
 
+    # add the diagrams
+    subprocess.run(
+        [
+            os.path.join(current_dir, "domain_contexts_diagrams.py"),
+            output_path,
+        ]
+    )
+
+    # incorporate the diagrams in each contexts doc
+    for file in glob(os.path.join(output_path, "*-entities.dot")):
+        base_name = os.path.basename(file)[:-13]
+        rst_file = os.path.join(output_path, f"{base_name}-toc.rst")
+        with open(rst_file, "r") as file_d:
+            rst_lines = file_d.readlines()
+        rst_lines.insert(3, f".. graphviz:: {base_name}-entities.dot\n\n")
+        with open(rst_file, "w") as file_d:
+            file_d.write("".join(rst_lines))
+
 
 def run_git_to_sphinx(_):
     """Add git content into doc"""