Merge pull request #97 from Gon-na/2024-02-13-main

Documentation: Adress Duplication, Chapter for KEMField Manual
KATRIN-Experiment · Feb 15, 2024 · 2ec8fb1 · 2ec8fb1
2 parents 29125f2 + 26129d6
commit 2ec8fb1
Show file tree

Hide file tree

Showing 11 changed files with 117 additions and 217 deletions.
diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml
@@ -11,7 +11,8 @@ jobs:
     - uses: actions/checkout@v3
 
     - name: Install dependencies
-      run: pip install sphinx_rtd_theme sphinx_design
+      run: pip install sphinx_rtd_theme sphinx_design m2r2 sphinx-simplepdf 
+
 
     - name: Build target "build"
       run: cd Documentation/gh-pages && make github

diff --git a/Documentation/gh-pages/Makefile b/Documentation/gh-pages/Makefile
@@ -18,7 +18,8 @@ github:
 	@rm -rf "$(HTMLDIR)"
 	@mv "$(BUILDDIR)/html" "$(HTMLDIR)"
 	@touch "$(HTMLDIR)/.nojekyll"
-
+	@mkdir "$(HTMLDIR)/kemfield"
+	@cp ../../KEMField/Documentation/manual/manual.pdf "$(HTMLDIR)/kemfield"
 .PHONY: help github Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

diff --git a/Documentation/gh-pages/source/KEMField_manual_link.rst b/Documentation/gh-pages/source/KEMField_manual_link.rst
@@ -0,0 +1,14 @@
+KEMField 
+**********
+
+
+**KEMField** is a toolkit that allows users to solve electrostatic and magnetostatic fields from user-defined inputs. 
+Detailed explanations on installation and implementation are available in the manual displayed below. 
+Alternatively the manual is available for download :download:`here <../../../KEMField/Documentation/manual/manual.pdf>` 
+and can also be found in the `Github repository <https://github.com/KATRIN-Experiment/Kassiopeia/>`_. 
+
+
+.. pdf-include:: ./kemfield/manual.pdf
+    :width: 100%
+    :height: 800px
+
diff --git a/Documentation/gh-pages/source/compiling.rst b/Documentation/gh-pages/source/compiling.rst
@@ -1,4 +1,4 @@
-Getting starting with Kassiopiea
+Getting started with Kassiopiea
 **********************************
 
 .. contents:: On this page

diff --git a/Documentation/gh-pages/source/conf.py b/Documentation/gh-pages/source/conf.py
@@ -42,7 +42,10 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.graphviz',
     'sphinx_rtd_theme',
-    'sphinx_design'
+    'sphinx_design',
+    'm2r2',
+    'sphinx_simplepdf',
+
 ]
 
 extlinks = {

diff --git a/Documentation/gh-pages/source/contact.rst b/Documentation/gh-pages/source/contact.rst
@@ -0,0 +1,46 @@
+
+Contact, Meeting and References
+*********************************
+
+You can `contribute changes <https://github.com/KATRIN-Experiment/Kassiopeia/compare>`_, `report issues <https://github.com/KATRIN-Experiment/Kassiopeia/issues/new>`_ and `join discussions <https://github.com/KATRIN-Experiment/Kassiopeia/discussions>`_ on Github.
+
+Join the Kassiopeia community on `Gitter <https://gitter.im/kassiopeia-simulation/community>`_.
+
+Contact
+=======
+
+*  Kasper development list: katrin-kasper@lists.kit.edu
+*  Richard Salomon: richardsalomon@uni-muenster.de
+*  Benedikt Bieringer: benedikt.b@uni-muenster.de
+
+
+
+Regular Meeting
+=======
+
+We also organize a regular meeting via Zoom. 
+
+Kassiopeia **users as well as developers** can join, ask questions, raise issues and discuss development topics. 
+It does not matter whether you are already an expert or a complete beginner. **Everyone is welcome!** 
+
+The meeting is announced via email. 
+Please register for the `mailing list <https://www.lists.kit.edu/sympa/subscribe/kassiopeia-user>`_ if you are interested. 
+
+
+References and Citation
+==========
+
+**Cite** |our paper|_\ **:**
+
+.. |our paper| replace:: **our paper**
+.. _our paper: https://iopscience.iop.org/article/10.1088/1367-2630/aa6950
+
+.. code-block:: bash
+
+    D. Furse et al. (2017) New J. Phys. 19 053012: “Kassiopeia: A Modern, Extensible C++ Particle Tracking Package” (doi:10.1088/1367-2630/aa6950)
+
+
+In addition to this user guide, *Kassiopeia* and its associated libraries have been documented extensively in several
+PhD theses. Many of these can be found under the list of KATRIN publications_.
+
+.. _publications: https://www.katrin.kit.edu/375.php
diff --git a/Documentation/gh-pages/source/external_documentation.rst b/Documentation/gh-pages/source/external_documentation.rst
diff --git a/Documentation/gh-pages/source/index.rst b/Documentation/gh-pages/source/index.rst
@@ -40,8 +40,8 @@ Welcome to Kassiopeia's documentation!
  .. toctree::
     :maxdepth: 4
 
-    Introduction <introduction.rst>
-    References, Citation and Contact <external_documentation.rst>
+    Contact, Meeting and References <contact.rst>
+    Introduction <introduction.rst> 
     Getting Started <compiling.rst>
     Examples and Tests <examples.rst>
     Configuring Your Own Simulation <configuration.rst>
@@ -51,9 +51,10 @@ Welcome to Kassiopeia's documentation!
     Additional Simulation Tools <tools.rst>
     Visualization Techniques <visualization.rst>
     XML Bindings <bindings.rst>
-    License <license.rst>
+    KEMField <KEMField_manual_link.rst>
+    License <linktolicense.rst>
     Authors <authors.rst>
- 
+
 
 
 
@@ -94,6 +95,9 @@ to run your first simulation! *Note: A VTK error indicates that the "VNC (Deskto
     D. Furse et al. (2017) New J. Phys. 19 053012: “Kassiopeia: A Modern, Extensible C++ Particle Tracking Package” (doi:10.1088/1367-2630/aa6950)
 
 
+In addition to this user guide, *Kassiopeia* and its associated libraries have been documented extensively in several
+PhD theses. Many of these can be found under the list of KATRIN publications_.
+
 **Docker images**
 --------------
 
@@ -106,6 +110,6 @@ The `kassiopeia/full` image comes with a JupyterLab installation, can run on Kub
 
 .. |More information| replace:: **More information**
 .. _More information: https://github.com/KATRIN-Experiment/Kassiopeia/blob/main/Docker/README.md
-
+.. _publications: https://www.katrin.kit.edu/375.php
 
 
diff --git a/Documentation/gh-pages/source/linktolicense.rst b/Documentation/gh-pages/source/linktolicense.rst
@@ -0,0 +1,3 @@
+
+.. mdinclude:: ../../../LICENSE.md
+
diff --git a/LICENSE.md b/LICENSE.md
@@ -7,26 +7,38 @@ All rights not expressly granted under this license are reserved.
 
 Installation, use, reproduction, display, modification and redistribution of this software, with or without modification, in source and binary forms, are permitted on a non-exclusive basis. Any exercise of rights by you under this license is subject to the following conditions:
 
-1. Redistributions of this software, in whole or in part, with or without modification, shall reproduce the above copyright notice and these license conditions in this software, the user documentation and any other materials provided with the redistributed software.  By using, copying, modifying or distributing the software (or any work based on the software) you agree to acknowledge its use in resulting scientific publications.
+1. 
+    Redistributions of this software, in whole or in part, with or without modification, shall reproduce the above copyright notice and these license conditions in this software, the user documentation and any other materials provided with the redistributed software.  By using, copying, modifying or distributing the software (or any work based on the software) you agree to acknowledge its use in resulting scientific publications.
 
-2. The user documentation, if any, included with a redistribution and derivatives, must include the following notice::
 
-    This product includes software developed by Members of the KATRIN Collaboration ( http://www.katrin.kit.edu )
+2. 
+   The user documentation, if any, included with a redistribution and derivatives, must include the following notice::
+
+             This product includes software developed by Members of the KATRIN Collaboration ( http://www.katrin.kit.edu )
+   If that is where third-party acknowledgments normally appear, this acknowledgment must be reproduced in the modified version of this software itself.
 
-If that is where third-party acknowledgments normally appear, this acknowledgment must be reproduced in the modified version of this software itself.
 
-3. The names `KATRIN`, `Kassiopeia`, `KEMField`, and `KGeoBag` may not be used to endorse or promote software, or products derived therefrom, except with prior written permission by the Copyright Holders. If this software is redistributed in modified form, the name and reference of the modified version must be clearly distinguishable from that of this software.
+3. 
+    The names `KATRIN`, `Kassiopeia`, `KEMField`, and `KGeoBag` may not be used to endorse or promote software, or products derived therefrom, except with prior written permission by the Copyright Holders. If this software is redistributed in modified form, the name and reference of the modified version must be clearly distinguishable from that of this software.
 
-4. You are under no obligation to provide anyone with any modifications of this software that you may develop, including but not limited to bug fixes, patches, upgrades or other enhancements or derivatives of the features, functionality or performance of this software. However, if you publish or distribute your modifications without contemporaneously requiring users to enter into a separate written license agreement, then you are deemed to have granted all of the Copyright Holders a license to your modifications, including modifications protected by any patent owned by you, under the conditions of this license.
 
-5. You may not include this software in whole or in part in any patent or patent application in respect of any modification of this software developed by you.
+4. 
+    You are under no obligation to provide anyone with any modifications of this software that you may develop, including but not limited to bug fixes, patches, upgrades or other enhancements or derivatives of the features, functionality or performance of this software. However, if you publish or distribute your modifications without contemporaneously requiring users to enter into a separate written license agreement, then you are deemed to have granted all of the Copyright Holders a license to your modifications, including modifications protected by any patent owned by you, under the conditions of this license.
+
+
+5. 
+    You may not include this software in whole or in part in any patent or patent application in respect of any modification of   this software developed by you.
+
 
 6. DISCLAIMER
 
-THIS SOFTWARE IS PROVIDED BY THE MEMBERS AND COPYRIGHT HOLDERS OF KASSIOPEIA "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, OF SATISFACTORY QUALITY, AND FITNESS FOR A PARTICULAR PURPOSE OR USE ARE DISCLAIMED. THE COPYRIGHT HOLDERS MAKE NO REPRESENTATION THAT THE SOFTWARE AND MODIFICATIONS THEREOF, WILL NOT INFRINGE ANY PATENT, COPYRIGHT, TRADE SECRET OR OTHER PROPRIETARY RIGHT.
+    THIS SOFTWARE IS PROVIDED BY THE MEMBERS AND COPYRIGHT HOLDERS OF KASSIOPEIA "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, OF SATISFACTORY QUALITY, AND FITNESS FOR A PARTICULAR PURPOSE OR USE ARE DISCLAIMED. THE COPYRIGHT HOLDERS MAKE NO REPRESENTATION THAT THE SOFTWARE AND MODIFICATIONS THEREOF, WILL NOT INFRINGE ANY PATENT, COPYRIGHT, TRADE SECRET OR OTHER PROPRIETARY RIGHT.
+
 
 7. LIMITATION OF LIABILITY
 
-THE COPYRIGHT HOLDERS SHALL HAVE NO LIABILITY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF USE, DATA OR PROFITS, OR BUSINESS INTERRUPTION, HOWEVER CAUSED AND ON ANY THEORY OF CONTRACT, WARRANTY, TORT (INCLUDING NEGLIGENCE), PRODUCT LIABILITY OR OTHERWISE, ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+    THE COPYRIGHT HOLDERS SHALL HAVE NO LIABILITY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF USE, DATA OR PROFITS, OR BUSINESS INTERRUPTION, HOWEVER CAUSED AND ON ANY THEORY OF CONTRACT, WARRANTY, TORT (INCLUDING NEGLIGENCE), PRODUCT LIABILITY OR OTHERWISE, ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
 
-8. This license shall terminate with immediate effect and without notice if you fail to comply with any of the terms of this license, or if you institute litigation against any Copyright Holders or Members of the KATRIN Collaboration with regard to this software.
+8. 
+    This license shall terminate with immediate effect and without notice if you fail to comply with any of the terms of this     license, or if you institute litigation against any Copyright Holders or Members of the KATRIN Collaboration with regard to this software.