Merge pull request #2 from 2xB/main

Documentation: Add source files for GitHub Pages
project8 · Oct 26, 2023 · 45c1ed6 · 45c1ed6
2 parents 802f17e + 64f9c04
commit 45c1ed6
Show file tree

Hide file tree

Showing 93 changed files with 26,604 additions and 0 deletions.
diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml
@@ -0,0 +1,43 @@
+name: Build GitHub Pages website
+
+on:
+  push:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Install dependencies
+      run: pip install sphinx_rtd_theme
+
+    - name: Build target "build"
+      run: cd Documentation/gh-pages && make github
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v2
+      with:
+        path: 'Documentation/gh-pages/docs'
+
+  # As documented on https://github.com/actions/deploy-pages
+  deploy:
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
diff --git a/Documentation/gh-pages/Makefile b/Documentation/gh-pages/Makefile
@@ -0,0 +1,27 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+HTMLDIR       = docs
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+github:
+	@make html
+	@rm -rf "$(HTMLDIR)"
+	@mv "$(BUILDDIR)/html" "$(HTMLDIR)"
+	@touch "$(HTMLDIR)/.nojekyll"
+
+.PHONY: help github 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)
diff --git a/Documentation/gh-pages/README b/Documentation/gh-pages/README
@@ -0,0 +1,10 @@
+Kassiopeia documentation
+========================
+
+This uses Sphinx. The provided Makefile rebuilds the GitHub HTML pages:
+
+    make github
+
+The used Sphinx theme is 'Read the Docs'. It can be installed via:
+
+    pip install sphinx_rtd_theme
diff --git a/Documentation/gh-pages/source/_images/KassiopeiaLogo_1_bb.png b/Documentation/gh-pages/source/_images/KassiopeiaLogo_1_bb.png
diff --git a/Documentation/gh-pages/source/_images/KassiopeiaLogo_1_cropped_bb.png b/Documentation/gh-pages/source/_images/KassiopeiaLogo_1_cropped_bb.png
diff --git a/Documentation/gh-pages/source/_images/adiabatic_step.png b/Documentation/gh-pages/source/_images/adiabatic_step.png
diff --git a/Documentation/gh-pages/source/_images/analytic_trap.png b/Documentation/gh-pages/source/_images/analytic_trap.png
diff --git a/Documentation/gh-pages/source/_images/beam_description.png b/Documentation/gh-pages/source/_images/beam_description.png
diff --git a/Documentation/gh-pages/source/_images/bindings_full.svg b/Documentation/gh-pages/source/_images/bindings_full.svg
diff --git a/Documentation/gh-pages/source/_images/cmake_empty_cache.png b/Documentation/gh-pages/source/_images/cmake_empty_cache.png
diff --git a/Documentation/gh-pages/source/_images/cmake_initial_config.png b/Documentation/gh-pages/source/_images/cmake_initial_config.png
diff --git a/Documentation/gh-pages/source/_images/cmake_initial_output.png b/Documentation/gh-pages/source/_images/cmake_initial_output.png
diff --git a/Documentation/gh-pages/source/_images/dipole_meshed_vtk.png b/Documentation/gh-pages/source/_images/dipole_meshed_vtk.png
diff --git a/Documentation/gh-pages/source/_images/dipole_potential_vs_z.png b/Documentation/gh-pages/source/_images/dipole_potential_vs_z.png
diff --git a/Documentation/gh-pages/source/_images/dipole_vtk.png b/Documentation/gh-pages/source/_images/dipole_vtk.png
diff --git a/Documentation/gh-pages/source/_images/exact_step.png b/Documentation/gh-pages/source/_images/exact_step.png
diff --git a/Documentation/gh-pages/source/_images/geometry_picture.png b/Documentation/gh-pages/source/_images/geometry_picture.png
diff --git a/Documentation/gh-pages/source/_images/geometry_tree.png b/Documentation/gh-pages/source/_images/geometry_tree.png
diff --git a/Documentation/gh-pages/source/_images/geometryviewer.png b/Documentation/gh-pages/source/_images/geometryviewer.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_annulus_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_annulus_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_beam_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_beam_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_box_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_box_space_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_cone_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_cone_space_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_cone_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_cone_surface_model.png
diff --git a/...on/gh-pages/source/_images/kgeobag_conic_section_port_housing_surface_model.png b/...on/gh-pages/source/_images/kgeobag_conic_section_port_housing_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_cut_cone_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_cut_cone_space_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_cut_cone_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_cut_cone_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_cut_cone_tube_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_cut_cone_tube_space_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_cut_torus_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_cut_torus_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_cylinder_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_cylinder_space_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_cylinder_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_cylinder_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_cylinder_tube_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_cylinder_tube_space_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_disk_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_disk_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_extruded_circle_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_extruded_circle_space_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_extruded_poly_loop_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_extruded_poly_loop_space_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_extruded_poly_loop_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_extruded_poly_loop_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_extruded_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_extruded_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_flattened_circle_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_flattened_circle_surface_model.png
diff --git a/...mentation/gh-pages/source/_images/kgeobag_flattened_poly_loop_surface_model.png b/...mentation/gh-pages/source/_images/kgeobag_flattened_poly_loop_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_multicut_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_multicut_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_port_housing_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_port_housing_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_rod_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_rod_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_rotated_arc_segment_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_rotated_arc_segment_space_model.png
diff --git a/...mentation/gh-pages/source/_images/kgeobag_rotated_arc_segment_surface_model.png b/...mentation/gh-pages/source/_images/kgeobag_rotated_arc_segment_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_rotated_circle_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_rotated_circle_space_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_rotated_circle_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_rotated_circle_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_rotated_line_segment_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_rotated_line_segment_space_model.png
diff --git a/...entation/gh-pages/source/_images/kgeobag_rotated_line_segment_surface_model.png b/...entation/gh-pages/source/_images/kgeobag_rotated_line_segment_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_rotated_poly_line_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_rotated_poly_line_space_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_rotated_poly_line_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_rotated_poly_line_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_rotated_poly_loop_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_rotated_poly_loop_space_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_rotated_poly_loop_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_rotated_poly_loop_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_rotated_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_rotated_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_shell_arc_segment_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_shell_arc_segment_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_shell_circle_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_shell_circle_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_shell_line_segment_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_shell_line_segment_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_shell_poly_line_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_shell_poly_line_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_shell_poly_loop_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_shell_poly_loop_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_teapot_mesh.png b/Documentation/gh-pages/source/_images/kgeobag_teapot_mesh.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_torus_space_model.png b/Documentation/gh-pages/source/_images/kgeobag_torus_space_model.png
diff --git a/Documentation/gh-pages/source/_images/kgeobag_torus_surface_model.png b/Documentation/gh-pages/source/_images/kgeobag_torus_surface_model.png
diff --git a/Documentation/gh-pages/source/_images/mesh_simulation.png b/Documentation/gh-pages/source/_images/mesh_simulation.png
diff --git a/Documentation/gh-pages/source/_images/meshviewer.png b/Documentation/gh-pages/source/_images/meshviewer.png
diff --git a/Documentation/gh-pages/source/_images/paraview.png b/Documentation/gh-pages/source/_images/paraview.png
diff --git a/Documentation/gh-pages/source/_images/paraview_histogram.png b/Documentation/gh-pages/source/_images/paraview_histogram.png
diff --git a/Documentation/gh-pages/source/_images/paraview_render.png b/Documentation/gh-pages/source/_images/paraview_render.png
diff --git a/Documentation/gh-pages/source/_images/paraview_sheet.png b/Documentation/gh-pages/source/_images/paraview_sheet.png
diff --git a/Documentation/gh-pages/source/_images/pmt_paraview.png b/Documentation/gh-pages/source/_images/pmt_paraview.png
diff --git a/Documentation/gh-pages/source/_images/quadrupole_vtk.png b/Documentation/gh-pages/source/_images/quadrupole_vtk.png
diff --git a/Documentation/gh-pages/source/_images/root_output.png b/Documentation/gh-pages/source/_images/root_output.png
diff --git a/Documentation/gh-pages/source/_images/run_event_track_step.png b/Documentation/gh-pages/source/_images/run_event_track_step.png
diff --git a/Documentation/gh-pages/source/_images/short_true_false.png b/Documentation/gh-pages/source/_images/short_true_false.png
diff --git a/Documentation/gh-pages/source/_images/sim_flow.png b/Documentation/gh-pages/source/_images/sim_flow.png
diff --git a/Documentation/gh-pages/source/_images/tools_axial_mesh_viewer.png b/Documentation/gh-pages/source/_images/tools_axial_mesh_viewer.png
diff --git a/Documentation/gh-pages/source/_images/tools_geometry_viewer.png b/Documentation/gh-pages/source/_images/tools_geometry_viewer.png
diff --git a/Documentation/gh-pages/source/_images/tools_geometry_viewer_root.png b/Documentation/gh-pages/source/_images/tools_geometry_viewer_root.png
diff --git a/Documentation/gh-pages/source/_images/toric.png b/Documentation/gh-pages/source/_images/toric.png
diff --git a/Documentation/gh-pages/source/authors.rst b/Documentation/gh-pages/source/authors.rst
@@ -0,0 +1,20 @@
+.. _authors-label:
+
+Authors
+*******
+
+Authors of Kassiopeia include individuals from the following institutions:
+
+- Karlsruhe Institute of Technology
+- Lawrence Berkeley National Laboratory
+- Massachusetts Institute of Technology
+- Max Planck Institute for Physics
+- University of California, Santa Barbara
+- University of Mainz
+- University of Manitoba
+- University of Muenster
+- University of North Carolina, Chapel Hill
+- University of Washington
+- University of Wuppertal
+
+Additional contributions were made by various GitHub users. Than you for your support!
diff --git a/Documentation/gh-pages/source/bindings.rst b/Documentation/gh-pages/source/bindings.rst
@@ -0,0 +1,52 @@
+.. _bindings-label:
+
+Bindings Documentation
+**********************
+
+This section provides documentation for the **XML bindings**. Many Kasper
+modules can parse XML files during intialization; the bindings classes define
+the available XML elements, their attributes and their relation to C++ classes.
+
+.. contents:: On this page
+    :local:
+    :depth: 2
+
+Overview
+========
+
+The files below show the allowed *elements* and *attributes* that can be used
+in Kasper XML files; according to the syntax:
+
+.. code-block:: xml
+
+    <element attribute_1="value_1" attribute_2="value_2">
+        <child_element attribute_3="value_3" />
+    </element>
+
+Elements can be nested according to what is shown here, and each element can
+have a number of attributes. Note that in some cases, certain child elements
+and attributes are required; in other cases, they are mutually exclusive. Note
+that this information is not represented here in the documentation.
+
+Additional documentation on the XML bindings is available on GitHub:
+`Documentation/Bindings <https://github.com/KATRIN-Experiment/Kassiopeia/blob/main/Documentation/Bindings/>`_.
+
+Bindings graph
+==============
+
+The graphs shows the relation between the available XML elements.
+
+.. image:: _images/bindings_full.svg
+    :width: 1000px
+    :alt: XML bindings graph
+
+List of bindings
+================
+
+The tables below show the child elements and attributes along with their type for each XML element.
+Note that the column pairs *child element / child type* and *attribute / attribute type* are linked: each listed type
+corresponds to the item on the left. The list of attributes is independent to the list of child elements. For many
+elements the child elements and attributes cannot be freely combined (e.g. some are mutually exclusive), but this is
+not reflected here.
+
+.. include:: ./bindings_full.rst
diff --git a/Documentation/gh-pages/source/bindings_full.rst b/Documentation/gh-pages/source/bindings_full.rst