First tests with a skeleton Sphinx folder.

docs/.gitignore

@@ -0,0 +1 @@
+_build

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -v
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.org

@@ -0,0 +1,47 @@
+#+TITLE: Documentation generation for BattInfo
+* Requirements
+** sphinx
+   installation instruction described [[https://www.sphinx-doc.org/en/master/usage/installation.html][here]]
+   #+begin_src
+     pip install sphinx
+   #+end_src
+** install sphinx pydata theme
+   https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html
+   #+begin_src
+     pip install pydata-sphinx-theme
+   #+end_src
+** globabsubs extension
+   #+begin_src
+     pip install sphinxcontrib-globalsubs
+   #+end_src
+** autosectionlabel
+   - part of default distribution
+   - We use ~autosectionlabel_prefix_document = True~ which means that the internal link must be prefixed by the file
+     name and a semi-column, see [[https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html][here]].
+
+* Workflow for editing
+
+  In the ~Documentation~ directory, run from terminal
+  #+BEGIN_SRC sh
+  make html
+  #+END_SRC
+
+  The command generates all the files for a static website and writes them in ~Documentation/_build/html~
+
+  All the files in this directory must then be copied to the ~BattInfo-doc~ [[https://github.com/BattMoTeam/BattMo-doc][repo]]. From there, make a *force* push. We do
+  not keep track of the history of the ouput files (html), but we of course keep track of the documentation source, directly in the
+  main repo ~BattInfo~.
+
+  The deployment of the webpage can be followed from the [[https://github.com/BattMoTeam/BattMo-doc/actions][github pages section]]
+
+  The result can be view at
+
+  https://battmoteam.github.io/Battinfo-doc/
+
+* Interesting Manuals
+** sphinx manual
+   https://www.sphinx-doc.org/en/master/contents.html
+** reStucturedText (rst) format
+   https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+* Configuration file
+  - ~conf.py~ see https://www.sphinx-doc.org/en/master/usage/configuration.html

docs/_static/css/custom.css

@@ -0,0 +1,75 @@
+td.element-table-key, td.element-table-value {
+    vertical-align: top;
+}
+
+td.element-table-key {
+    text-align: right;
+    padding-right: 2mm;
+    width: 20%;
+}
+
+span.element-table-key {
+    font-weight: bold;
+}
+
+table.element-table {
+    width: 100%;
+    text-align: left;
+}
+
+html table.element-table tr:nth-child(odd) td{
+   background-color: Gainsboro;
+}
+
+table.element-table tr:nth-child(even) td{
+   background-color: GhostWhite;
+}
+
+html[data-theme=dark] table.element-table tr:nth-child(odd) td{
+   background-color: black;
+}
+
+html[data-theme=dark] table.element-table tr:nth-child(even) td{
+   background-color: black;
+}
+body img, body svg {
+    background-color: transparent;
+}
+html[data-theme='dark'] .bd-content img.my-svg,
+html[data-theme='dark'] .bd-content svg.my-svg {
+    background: transparent !important;
+    filter: none !important;
+    color: white !important;
+    fill: white !important;
+    stroke: white !important;
+}
+html:not([data-theme='light']) .bd-content img.my-svg,
+html:not([data-theme='light']) .bd-content svg.my-svg {
+    color: black !important;
+    fill: black !important;
+    stroke: black !important;
+}
+.faq-section summary {
+    font-size: 1.2em; /* Adjust the size as needed */
+    color: #3D98B6; /* This is a bluish color */
+    font-weight: bold; /* Makes the font bold */
+    cursor: pointer; /* Changes the cursor to indicate it's clickable */
+}
+
+#jsoncrackEmbed {
+  flex: 1;
+  order: 2;
+  width: 100%;
+  height: 100vh;
+  border: none;
+}
+/* this fixes darkmode within the json-ld playground iframe
+by inverting all colors if darkmode is active */
+html[data-theme="dark"] iframe[src*="json-ld.org/playground"] {
+   filter: invert(0.9);
+}
+
+
+
+
+

docs/assets/img/graph.html

@@ -0,0 +1,155 @@
+<html>
+    <head>
+        <meta charset="utf-8">
+
+            <script src="lib/bindings/utils.js"></script>
+            <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/vis-network/9.1.2/dist/dist/vis-network.min.css" integrity="sha512-WgxfT5LWjfszlPHXRmBWHkV2eceiWTOBvrKCNbdgDYTHrT2AeLCGbF4sZlZw3UMN3WtL0tGUoIAKsu8mllg/XA==" crossorigin="anonymous" referrerpolicy="no-referrer" />
+            <script src="https://cdnjs.cloudflare.com/ajax/libs/vis-network/9.1.2/dist/vis-network.min.js" integrity="sha512-LnvoEWDFrqGHlHmDD2101OrLcbsfkrzoSpvtSQtxK3RMnRV0eOkhhBN2dXHKRrUU8p2DGRTk35n4O8nWSVe1mQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+
+
+<center>
+<h1></h1>
+</center>
+
+<!-- <link rel="stylesheet" href="../node_modules/vis/dist/vis.min.css" type="text/css" />
+<script type="text/javascript" src="../node_modules/vis/dist/vis.js"> </script>-->
+        <link
+          href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.0-beta3/dist/css/bootstrap.min.css"
+          rel="stylesheet"
+          integrity="sha384-eOJMYsd53ii+scO/bJGFsiCZc+5NDVN2yr8+0RDqr0Ql0h+rP48ckxlpbzKgwra6"
+          crossorigin="anonymous"
+        />
+        <script
+          src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.0-beta3/dist/js/bootstrap.bundle.min.js"
+          integrity="sha384-JEW9xMcG8R+pH31jmWH6WWP0WintQrMb4s7ZOdauHnUtxwoG2vI5DkLtS3qm9Ekf"
+          crossorigin="anonymous"
+        ></script>
+
+
+        <center>
+          <h1></h1>
+        </center>
+        <style type="text/css">
+
+             #mynetwork {
+                 width: 100%;
+                 height: 100%;
+                 background-color: #222222;
+                 border: 1px solid lightgray;
+                 position: relative;
+                 float: left;
+             }
+
+
+
+
+
+
+        </style>
+    </head>
+
+
+    <body>
+        <div class="card" style="width: 100%">
+
+
+            <div id="mynetwork" class="card-body"></div>
+        </div>
+
+
+
+
+        <script type="text/javascript">
+
+              // initialize global variables.
+              var edges;
+              var nodes;
+              var allNodes;
+              var allEdges;
+              var nodeColors;
+              var originalNodes;
+              var network;
+              var container;
+              var options, data;
+              var filter = {
+                  item : '',
+                  property : '',
+                  value : []
+              };
+
+
+
+
+
+              // This method is responsible for drawing the graph, returns the drawn network
+              function drawGraph() {
+                  var container = document.getElementById('mynetwork');
+
+
+
+                  // parsing and collecting nodes and edges from the python
+                  nodes = new vis.DataSet([{"color": "#97c2fc", "font": {"color": "white"}, "id": "ClassA", "label": "ClassA", "shape": "dot"}, {"color": "#97c2fc", "font": {"color": "white"}, "id": "ClassB", "label": "ClassB", "shape": "dot"}, {"color": "#97c2fc", "font": {"color": "white"}, "id": "ClassC", "label": "ClassC", "shape": "dot"}, {"color": "#97c2fc", "font": {"color": "white"}, "id": "ClassD", "label": "ClassD", "shape": "dot"}]);
+                  edges = new vis.DataSet([{"from": "ClassA", "to": "ClassB"}, {"from": "ClassA", "to": "ClassC"}, {"from": "ClassB", "to": "ClassD"}]);
+
+                  nodeColors = {};
+                  allNodes = nodes.get({ returnType: "Object" });
+                  for (nodeId in allNodes) {
+                    nodeColors[nodeId] = allNodes[nodeId].color;
+                  }
+                  allEdges = edges.get({ returnType: "Object" });
+                  // adding nodes and edges to the graph
+                  data = {nodes: nodes, edges: edges};
+
+                  var options = {
+    "configure": {
+        "enabled": false
+    },
+    "edges": {
+        "color": {
+            "inherit": true
+        },
+        "smooth": {
+            "enabled": true,
+            "type": "dynamic"
+        }
+    },
+    "interaction": {
+        "dragNodes": true,
+        "hideEdgesOnDrag": false,
+        "hideNodesOnDrag": false
+    },
+    "physics": {
+        "enabled": true,
+        "stabilization": {
+            "enabled": true,
+            "fit": true,
+            "iterations": 1000,
+            "onlyDynamicEdges": false,
+            "updateInterval": 50
+        }
+    }
+};
+
+
+
+
+
+
+                  network = new vis.Network(container, data, options);
+
+
+
+
+
+
+
+
+
+
+                  return network;
+
+              }
+              drawGraph();
+        </script>
+    </body>
+</html>