Merge branch 'master-docs-fix-images' into 'master'

Docs: fix images

See merge request !46

documentation/.gitignore

 # MkDocs output
 _build
 
+# Python temp files
+__pycache__
+
 # Python3 virtual env for MkDocs packages
 venvp3

documentation/create_activate_virtualenv_p3.sh

@@ -22,7 +22,7 @@ pip install mkdocs-mermaid2-plugin # adds support for mermaid diagrams / flowcha
 
 
 
-echo "\n\n\nSuccess!!\nYou can now build and serve the web iste locally by running: 'brew serve'"
+echo "\n\n\nSuccess!!\nYou can now build and serve the web iste locally by running: 'mkdocs serve'"
 echo "\n[Note: if you have mkdocs installed on your system folders already, to avoid errors about missing packages, you might have to run the one in the virtualenv explicitely, by running: './venvp3/bin/mkdocs serve']"
 
 echo "\nThen, when you finished working with mkdocs, you can close the virtual environment by running: 'deactivate'\n\n"

documentation/docs/components/kernel/reference/RCBase/GeoShape/GeoBox.md

@@ -16,10 +16,12 @@
 The constructor fills the box with the $x$, $y$, and $z$ *half-lengths*, and the accessors return those quantities.
 
 
-<figure>
-  <img src="/components/kernel/reference/RCBase/GeoShape/GeoBox.png" width="400" />
-  <figcaption>Figure 2: A GeoBox object, representing a rectangular prism or “box”.</figcaption>
-</figure>
+{{ imgutils_image_caption('RCBase/GeoShape/GeoBox.png', 
+   alt='The GeoBox shape', 
+   cap='Figure 2: A GeoBox object, representing a rectangular prism or “box”.',
+   urlFix=False) 
+}}
+
 
 
 

documentation/docs/components/kernel/reference/RCBase/GeoShape/GeoCons.md

 ### GeoCons
 
+
 ```cpp
 // === GeoCons ===
 
@@ -20,9 +21,12 @@
 
 A `GeoCons` represents a cone section positioned with its axis along the $z$ direction, and is specified by a starting value of $\phi$, a total subtended angle in $\phi$, a *half-width* in $z$, and minimum and maximum values of radius at both extremities in $z$.  The constructor specifies the values of these constants, and the accessors return them.
 
-<figure>
-  <img src="/components/kernel/reference/RCBase/GeoShape/GeoCons.png" width="400" />
-  <figcaption>Figure 3:  A GeoCons Object, representing a cone section.</figcaption>
-</figure>
+
+{{ imgutils_image_caption('RCBase/GeoShape/GeoCons.png', 
+   alt='The GeoCons shape', 
+   cap='Figure: A GeoCons Object, representing a cone section.',
+   urlFix=False) 
+}}
+
 
 

documentation/docs/components/kernel/reference/RCBase/GeoShape/GeoPara.md

@@ -19,11 +19,18 @@
 
 The `GeoPara` class represents a parallelepiped. Faces at $\pm z$ are parallel to the $x-y$ plane. One edge of each of these faces is parallel to the $x$-axis, while the other edge makes an angle $\alpha$ with respect to the $y$-axis.  The remaining edge of the parallelepiped is oriented along a vector whose polar angle is $\theta$ and whose azimuthal angle is $\phi$.  *Half-lengths* in $x$, $y$, and $z$ describe the projections of the sides of the parallelepiped project onto the coordinate axes.  The constructor fills these data, while the accessors return them.
 
-*Note:  Visualization of GeoPara is on the to-do list.*
 
-<figure>
-  <img src="https://dummyimage.com/600x400/eee/aaa" width="400" />
-  <figcaption>Figure 4: GeoPara object, representing a parallelepiped.</figcaption>
-</figure>
+
+!!! warning
+
+    Visualization of GeoPgon is on the to-do list.
+
+
+
+{{ imgutils_image_caption('https://dummyimage.com/600x400/eee/aaa', 
+   alt='The GeoPara shape', 
+   cap='Figure: GeoPara object, representing a parallelepiped.',
+   urlFix=False) 
+}}
 
 

documentation/docs/components/kernel/reference/RCBase/GeoShape/GeoPcon.md

@@ -22,14 +22,17 @@
 
 When the polycone is constructed, only $\phi_0$ and $\phi$ are given; then, the information at each $z$ location is given, one plane at a time, by using the `addPlane()` method.  At least two planes must be given, otherwise the polycone is not valid and methods such as `volume()` will fail and throw an exception.  The `isValid()` method can be used to determine whether the polycone has at least two planes.
 
+
 !!! note
 
     A polycone (`GeoPcon`) with exactly two planes is equivalent geometrically to a cone section (`GeoCons`).
 
 
-<figure>
-  <img src="/components/kernel/reference/RCBase/GeoShape/GeoPcon.png" width="400" />
-  <figcaption>Figure 2: A GeoPcon object, representing a "polycone", which is a union of cone sections.</figcaption>
-</figure>
+
+{{ imgutils_image_caption('RCBase/GeoShape/GeoPcon.png', 
+   alt='The GeoPcon shape', 
+   cap='Figure: A GeoPcon object, representing a "polycone", which is a union of cone sections.',
+   urlFix=False) 
+}}
 
 

documentation/docs/components/kernel/reference/RCBase/GeoShape/GeoPgon.md

@@ -23,12 +23,19 @@
 
 The constructor takes $\phi$ , $\phi_0$, and the number of sides in the cross-section as arguments; then, the information at each $z$ location is given, one plane at a time, by using the `addPlane()` method.  At least two planes must be given, otherwise the polygon is not valid and methods such as `volume()` will fail and throw an exception.  The `isValid()` method can be used to determine whether the polygon has at least two planes.
 
-*Note:  Visualization of GeoPgon is on the to-do list.*
 
-<figure>
-  <img src="https://dummyimage.com/600x400/eee/aaa" width="400" />
-  <figcaption>Figure 4: GeoPgon object, representing a polycone with a polygonal cross section.</figcaption>
-</figure>
+
+!!! warning
+
+    Visualization of GeoPgon is on the to-do list.
+
+
+{{ imgutils_image_caption('https://dummyimage.com/600x400/eee/aaa', 
+   alt='The GeoPgon shape', 
+   width='400', 
+   cap='Figure: GeoPgon object, representing a polycone with a polygonal cross section.',
+   urlFix=False) 
+}}
 
 
 

documentation/docs/components/kernel/reference/RCBase/GeoShape/GeoTrap.md

@@ -30,7 +30,13 @@ The two edges not parallel to the $x$-axis make an angle of $\alpha_n$ (`Angleyd
 
 The constructor fills the `GeoTrap` with these values and the accessors return them.
 
-<figure>
-  <img src="/components/kernel/reference/RCBase/GeoShape/GeoTrap.png" width="400" />
-  <figcaption>Figure 2: A GeoTrap object, representing a very general kind of trapezoid.</figcaption>
-</figure>
+
+{{ imgutils_image_caption('RCBase/GeoShape/GeoTrap.png', 
+   alt='The GeoTrap shape', 
+   cap='Figure: A GeoTrap object, representing a very general kind of trapezoid.',
+   urlFix=False) 
+}}
+
+
+
+

documentation/docs/components/kernel/reference/RCBase/GeoShape/GeoTrd.md

@@ -22,9 +22,11 @@ A `GeoTrd` is a simple trapezoid.  Two faces at $\pm \Delta z$ are parallel to e
 The constructor fills the object with these values and the accessors return them.
 
 
-<figure>
-  <img src="/components/kernel/reference/RCBase/GeoShape/GeoTrd.png" width="400" />
-  <figcaption>Figure 8: A GeoTrd object, representing a simple trapezoid.</figcaption>
-</figure>
+
+{{ imgutils_image_caption('RCBase/GeoShape/GeoTrd.png', 
+   alt='The GeoTrd shape', 
+   cap='Figure: A GeoTrd object, representing a simple trapezoid.',
+   urlFix=False) 
+}}
 
 

documentation/docs/components/kernel/reference/RCBase/GeoShape/GeoTube.md

@@ -18,10 +18,13 @@ The `GeoTube` class represents a tube, specified by an inner radius (`RMin`), an
 The constructor fills these quantities and the accessors return them.
 
 
-<figure>
-  <img src="/components/kernel/reference/RCBase/GeoShape/GeoTube.png" width="400" />
-  <figcaption>Figure 2: A GeoTube object, representing a tube or "pipe".</figcaption>
-</figure>
+
+{{ imgutils_image_caption('RCBase/GeoShape/GeoTube.png', 
+   alt='The GeoTube shape', 
+   cap='Figure N: A GeoTube object, representing a tube or "pipe".',
+   urlFix=False) 
+}}
+
 
 
 

documentation/docs/components/kernel/reference/RCBase/GeoShape/GeoTubs.md

@@ -20,8 +20,13 @@ A `GeoTubs` is a tube section; a tube that subtends some plane angle (less than
 
 Member functions provide access to these quantities.
 
-<figure>
-  <img src="/components/kernel/reference/RCBase/GeoShape/GeoTubs.png" width="400" />
-  <figcaption>Figure 7: A GeoTubs object, representing a tube section.</figcaption>
-</figure>
+
+{{ imgutils_image_caption('RCBase/GeoShape/GeoTubs.png', 
+   alt='The GeoTubs shape', 
+   cap='Figure: A GeoTubs object, representing a tube section.',
+   urlFix=False) 
+}}
+
+
+
 

documentation/docs/components/kernel/reference/Shapes.md

@@ -2,9 +2,10 @@
 
 ##	Shapes
 
+
 ### Introduction
 
-The shape classes in the geometry kernel are data structures designed to describe several geometrical primitives. Table 1 describes the different shapes presently provided within the geometry kernel.  This set is extensible; one only needs to derive a new shape from the base class and insure that it fits the pattern described below. Shapes are reference- counted objects, as described in [1.3.2.6][#].
+The shape classes in the geometry kernel are data structures designed to describe several geometrical primitives. Table 1 describes the different shapes presently provided within the geometry kernel.  This set is extensible; one only needs to derive a new shape from the base class and insure that it fits the pattern described below. Shapes are reference-counted objects, as described in [Reference Counting](#reference-counting).
 
 
 | Class   | Shape |
@@ -86,23 +87,23 @@ The classes `GeoShapeShift`, `GeoShapeUnion`, `GeoShapeSubtraction`, and `GeoSha
 
 We now present the interfaces to specific shapes.  In general these shapes are by default constructed as symmetrically around the origin as possible.  
 
-{!components/kernel/reference/RCBase/GeoShape/GeoBox.md!}
+{% include 'components/kernel/reference/RCBase/GeoShape/GeoBox.md' %}
 
-{!components/kernel/reference/RCBase/GeoShape/GeoCons.md!}
+{% include 'components/kernel/reference/RCBase/GeoShape/GeoCons.md' %}
 
-{!components/kernel/reference/RCBase/GeoShape/GeoPara.md!}
+{% include 'components/kernel/reference/RCBase/GeoShape/GeoPara.md' %}
 
-{!components/kernel/reference/RCBase/GeoShape/GeoPcon.md!}
+{% include 'components/kernel/reference/RCBase/GeoShape/GeoPcon.md' %}
 
-{!components/kernel/reference/RCBase/GeoShape/GeoPgon.md!}
+{% include 'components/kernel/reference/RCBase/GeoShape/GeoPgon.md' %}
 
-{!components/kernel/reference/RCBase/GeoShape/GeoTrap.md!}
+{% include 'components/kernel/reference/RCBase/GeoShape/GeoTrap.md' %}
 
-{!components/kernel/reference/RCBase/GeoShape/GeoTube.md!}
+{% include 'components/kernel/reference/RCBase/GeoShape/GeoTube.md' %}
 
-{!components/kernel/reference/RCBase/GeoShape/GeoTubs.md!}
+{% include 'components/kernel/reference/RCBase/GeoShape/GeoTubs.md' %}
 
-{!components/kernel/reference/RCBase/GeoShape/GeoTrd.md!}
+{% include 'components/kernel/reference/RCBase/GeoShape/GeoTrd.md' %}
 
 
 

documentation/docs/components/kernel/reference/index.md

 # GeoModel Kernel Class Reference
 
+
 This section describes in more detail the classes in the geometry kernel. In most cases we provide the class interface. In cases where part of the interface is used only internally by the geometry kernel itself and not by other users. In such cases we present a simplified picture of the interfaces.
 
 Detailed descriptions of the geometry kernel classes follow.
 
 
 
-{!components/kernel/reference/ReferenceCounting.md!}
+{% include 'components/kernel/reference/ReferenceCounting.md' %}
 
-{!components/kernel/reference/Materials_Elements.md!}
+{% include 'components/kernel/reference/Materials_Elements.md' %}
 
-{!components/kernel/reference/Shapes.md!}
+{% include 'components/kernel/reference/Shapes.md' %} 
 
-{!components/kernel/reference/LogicalVolumes.md!}
+{% include 'components/kernel/reference/LogicalVolumes.md' %}
 
-{!components/kernel/reference/PhysicalVolumes.md!}
+{% include 'components/kernel/reference/PhysicalVolumes.md' %}
 
-{!components/kernel/reference/Transformations.md!}
+{% include 'components/kernel/reference/Transformations.md' %}
 
-{!components/kernel/reference/NameTags.md!}
+{% include 'components/kernel/reference/NameTags.md' %}
 
 
 

documentation/docs/index.md

@@ -15,4 +15,12 @@ The external dependencies are minimal:
 
 ----
 
-*This Documentation is Work In Progress*
+<i>Last update:</i> 
+{% if git.status %}
+  <i> {{ git.date.strftime("%b %d, %Y -- %H:%M") or now() }} </i>
+{% else %}
+  <i> {{ now() }} </i> 
+{% endif %}
+
+
+

documentation/imgutils.py

+"""
+
+'imgutils'
+
+Utility macros to handle images, captions, and related things.
+
+Author: Riccardo Maria BIANCHI <riccardo.maria.bianchi@cern.ch>
+
+12 Jan 2021
+"""
+
+import math
+
+def define_env(env):
+    """
+    Utility macros to handle images, captions, and related things.
+    """
+
+    # import the predefined macro
+    fix_url = env.variables.fix_url # make relative urls point to root
+    
+    # activate trace
+    chatter = env.start_chatting("imgutils")
+
+
+    @env.macro
+    def imgutils_image(url:str, alt:str=''):
+        "Add an image within <figure> tags. Optionally, you can set an alternate-text" 
+        url2:str = url
+        if urlFix : 
+            url2 = fix_url(url)
+            chatter("Fixing image's URL: %s --> %s" % (url, url2))
+        return '<img src="%s", alt="%s">' % (url2, alt)
+
+    @env.macro
+    def imgutils_image_caption(url:str, alt:str='', width:int=400, cap:str='', urlFix:bool=True):
+        "Add an image within <figure> tags. Optionally, you can set a caption, an alternate-text, and a width value." 
+        url2:str = url
+        if urlFix : 
+            url2:str = fix_url(url)
+            chatter("Fixing image's URL: %s --> %s" % (url, url2))
+        return '<figure> <img src="%s", alt="%s", width="%s"> <figcaption>%s<figcaption> </figure>' % ( url2, alt, width, cap)
+
+
+    @env.macro
+    def imgutils_doc_env():
+        """
+        Document the environment, for development/debugging. 
+        (Hint: Use it in your .md file within a code block, i.e. as: 
+           ```
+           {{ doc_env() | pprint }}
+           ```
+        """
+        return {name:getattr(env, name) for name in dir(env) if not name.startswith('_')}
+
+

documentation/mkdocs.yml

@@ -4,6 +4,7 @@ site_author: ATLAS Collaboration & Contributors
 site_url: https://cern.ch/geomodel/home
 repo_name: GeoModel
 repo_url: https://gitlab.cern.ch/GeoModelDev/GeoModel
+site_author: geomodel-developers@cern.ch
 
 theme:
     name: material
@@ -29,6 +30,7 @@ nav:
         - Kernel:
             - 'Overview': 'components/kernel/overview/index.md'
             - 'Class Reference': 'components/kernel/reference/index.md'
+              #- 'Box': 'components/kernel/reference/RCBase/GeoShape/GeoBox.md'
     - For Developers:
         - 'Build the Libraries and Tools': 'dev/index.md'
         - 'Install single packages': 'dev/install-single-packages.md'
@@ -60,9 +62,11 @@ markdown_extensions:
 
 plugins:
   - search
-  - macros
+  - macros:
+        module_name: imgutils
+        verbose: true # enables debug through the 'chatter' method
   - mermaid2 # for diagrams
-  #- git-revision-date #TODO: teh mkdocs docker image apparently lacks the git exec, so this cannot be used. Update the image!
+  #- git-revision-date #TODO: the mkdocs docker image apparently lacks the git exec, so this cannot be used. Update the image!
 
 extra_javascript:
   - javascripts/config.js