Add to and

documentation/docs/dev/docs-contrib.md

+
+# How to contribute to the documentation
+
+## Get the documentation code
+
+The GeoModel documentation is stored within the main GeoModel code repository.
+
+To get the latest documentation, simply clone the repository:
+
+```
+git clone https://gitlab.cern.ch/GeoModelDev/GeoModel.git
+```
+
+Then, navigate to the documentation directory:
+
+```
+cd GeoModel/documentation
+```
+
+## How to update the documentation
+
+The documentation uses the documentation engine [MkDocs](https://www.mkdocs.org/) to transform documentation written in Markdown to HTML static files.
+
+It also uses the [Material](https://squidfunk.github.io/mkdocs-material/) theme for MkDocs, which offers many tools to handle additional documentation metadata.
+
+In order to update the documentation, you don't need to install `MkDocs` locally, because its build is performed within the GitLab CI (Continuos Integration) pipelines and then the HTML outcome is installed on the GeoModel server at CERN. 
+
+Thus, if you only want to update the documentation, you can merely:
+
+1. fork the GeoModel repository
+2. edit the documentation files you want to update
+3. push your changes
+4. create a Merge Request to get your changes merged into the GeoModel `master` branch
+
+However, if you want to preview your changes on your machine---and we recommend that---, you need to install `MkDocs` on your machine.
+
+
+## Dependencies - MkDocs
+
+On macOS, you can install `MkDocs` with [Homebrew](https://brew.sh):
+
+```
+brew install mkdocs
+```
+
+## Build and serve
+
+From the `documentation` folder, you can run
+
+```
+mkdocs serve
+```
+
+This will build the documentation and will start a local web server to serve it on a local port.
+
+You will get a message like this, at the end of the process:
+
+```
+[I 201201 19:05:55 server:296] Serving on http://127.0.0.1:8000
+```
+
+Open a web browser tab and enter the address you got, including the port number:
+
+```
+http://127.0.0.1:8000
+```
+
+You will be able to preview the documentation web site, and that will be automatically rebuilt and reloaded in the browser as soon as you change a documentation file.
+
+
+

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

+
+### GeoBox
+
+```cpp
+// === GeoBox ===
+
+   //Constructor:
+   GeoBox (double XHalfLength, double YHalfLength, double ZHalfLength)
+
+   //Public Methods:
+   double getXHalfLength() const
+   double getYHalfLength() const
+   double getZHalfLength() const
+```
+
+The constructor fills the box with the $x$, $y$, and $z$ *half-lengths*, and the accessors return those quantities.
+
+
+<figure>
+  <img src="/reference/RCBase/GeoShape/GeoBox.png" width="300" />
+  <figcaption>Figure 2: GeoBox object, representing a rectangular prism or “box”.</figcaption>
+</figure>
+
+
+

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

+### GeoCons
+
+```cpp
+// === GeoCons ===
+
+   // Constructor:
+   GeoCons (double RMin1, double RMin2,   
+            double RMax1, double RMax2, 
+            double DZ,  double SPhi,  double DPhi)
+
+   // Public Methods:
+   double getRMin1() const
+   double getRMin2() const
+   double getRMax1() const
+   double getRMax2() const
+   double getDZ() const
+   double getSPhi() const
+   double getDPhi() const
+```
+
+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="/reference/RCBase/GeoShape/GeoCons.png" width="300" />
+  <figcaption>Figure 3:  A GeoCons Object, representing a cone section.</figcaption>
+</figure>
+
+

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

+
+### GeoPara
+
+```cpp
+// === GeoPara ===
+
+  // Constructor:
+  GeoPara (double XHalfLength, double YHalfLength, double ZHalfLength,
+           double Alpha, double Theta, double Phi)
+
+  // Public Methods:
+  double getXHalfLength() const
+  double getYHalfLength() const
+  double getZHalfLength() const
+  double getTheta() const
+  double getAlpha() const
+  double getPhi() const
+```
+
+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="300" />
+  <figcaption>Figure 4: GeoPara object, representing a parallelepiped.</figcaption>
+</figure>
+
+

documentation/docs/reference/reference.md

@@ -142,5 +142,14 @@ All GeoShapes have the following interface:
 ```
 
 The classes `GeoShapeShift`, `GeoShapeUnion`, `GeoShapeSubtraction`, and `GeoShapeIntersection` are internal and should be considered for experts.  We will not discuss them further.  
+
 We now present the interfaces to specific shapes.  In general these shapes are by default constructed as symmetrically around the origin as possible.  
 
+{!reference/RCBase/GeoShape/GeoBox.md!}
+
+{!reference/RCBase/GeoShape/GeoCons.md!}
+
+{!reference/RCBase/GeoShape/GeoPara.md!}
+
+
+

documentation/docs/start/install.md

@@ -67,7 +67,7 @@ brew install geomodel
 
 !!! tip
     
-    If you experience problems in installing GeoModel packages with brew or using them, please try to clean your system from old packages or repositories. For that, please refer to the [Troubleshooting page](dev/troubleshooting.md).
+    If you experience problems in installing GeoModel packages with brew or using them, please try to clean your system from old packages or repositories. For that, please refer to the [Troubleshooting page](/dev/troubleshooting.md).
 
 
 

documentation/docs/team.md

@@ -16,7 +16,7 @@ The GeoModelKernel library has been extracted from the ATLAS software and comple
 The original, ATLAS-only version of the GeoModelKernel library was developed by *Joseph Boudreau* and *Vakhtang Tsulaia*, and presented at CHEP 2004 [^n1].
 
 
-The list of all contributors can be found in the [Contributors](dev/contribs.md) page.
+The list of all contributors can be found in the [Contributors](dev/contributors.md) page.
 
 
 [^n1]: See the references listed in the [Papers](papers/public.md) section. "CHEP" stands for _Computing in High Energy Physics_: that is the major conference where new tools and techniques in Software and Computing techniques for particle physics experiments are presented.

documentation/mkdocs.yml

@@ -25,9 +25,10 @@ nav:
         - 'Internal': 'papers/internal.md'
     - Reference:  'reference/reference.md'
     - For Developers:
-        - 'Build the Libraries': 'dev/index.md'
+        - 'Build the Libraries and Tools': 'dev/index.md'
         - 'Troubleshooting': 'dev/troubleshooting.md'
         - 'Doxygen documentation': https://cern.ch/geomodel/doxygen
+        - 'Contributing to the Documentation': 'dev/docs-contrib.md'
     - Team & History: 'team.md'
     - Contacts: 'contacts.md'
 extra_css: