From c7388ed7faff85f39fec0aa0a128aecf4ca1301c Mon Sep 17 00:00:00 2001 From: c-goen <105125661+Gon-na@users.noreply.github.com> Date: Tue, 14 Nov 2023 17:55:29 +0100 Subject: [PATCH] Welcome page of documentation: added README.md contents (#81) * README contents to Welcome Page * Fix 1 README contents to Documentation * Fix 2 README contents to Welcome Page * Fix 3 README contents to Welcome Page * Fix 3 README contents to Welcome Page * Fix 4 README contents to Welcome Page * Fix 4 README contents to Welcome Page * Fix 4 README contents to Welcome Page * removed duplicate image * removed duplicate image and contents from welcome page * Removal of Contents * Restored Contents and Search * test toctree depth 1 * test toctree maxdepth 0 * toctree maxdepth recovered to 4 * hidden toctree, deleted search Page * includehidden * test toctree * hidden * hidden2 * hidden3 * hidden4 * Link to SC * Link to SC 2 * Link to SC 3 * Update wording around Kasper components Co-authored-by: 2xB <31772910+2xB@users.noreply.github.com> * Added toctree dropdown and link to Docker/README.md * Fix 1 Added toctree dropdown and link to Docker/README.md * Fix 2 Added toctree dropdown and link to Docker/README.md * Fix 3 Added toctree dropdown and link to Docker/README.md * Added sphinx_design for dropdown-menu support * Added sphinx_design for dropdown-menu support * Proper cropdown code, moved to top of page * Dropdown test --------- Co-authored-by: 2xB <31772910+2xB@users.noreply.github.com> --- .github/workflows/github-pages.yml | 2 +- Documentation/gh-pages/source/conf.py | 1 + Documentation/gh-pages/source/index.rst | 96 +++++++++++++++++-- .../gh-pages/source/introduction.rst | 2 +- 4 files changed, 89 insertions(+), 12 deletions(-) diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml index 16cfff5ab..fc0eead39 100644 --- a/.github/workflows/github-pages.yml +++ b/.github/workflows/github-pages.yml @@ -11,7 +11,7 @@ jobs: - uses: actions/checkout@v3 - name: Install dependencies - run: pip install sphinx_rtd_theme + run: pip install sphinx_rtd_theme sphinx_design - name: Build target "build" run: cd Documentation/gh-pages && make github diff --git a/Documentation/gh-pages/source/conf.py b/Documentation/gh-pages/source/conf.py index 00156671d..65d280f85 100644 --- a/Documentation/gh-pages/source/conf.py +++ b/Documentation/gh-pages/source/conf.py @@ -42,6 +42,7 @@ 'sphinx.ext.mathjax', 'sphinx.ext.graphviz', 'sphinx_rtd_theme', + 'sphinx_design' ] extlinks = { diff --git a/Documentation/gh-pages/source/index.rst b/Documentation/gh-pages/source/index.rst index 5389f131d..b6a2dc17a 100644 --- a/Documentation/gh-pages/source/index.rst +++ b/Documentation/gh-pages/source/index.rst @@ -3,16 +3,41 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to Kassiopeia's documentation! -************************************** -.. image:: _images/KassiopeiaLogo_1_bb.png - :width: 250pt +|Release github| |Code Size| |Issues github| |Pull Requests github| +|Last Commit github| |Contributors github| |Gitter github| |Binder github| + +.. |Release github| image:: https://img.shields.io/github/v/release/KATRIN-Experiment/Kassiopeia + :target: https://github.com/KATRIN-Experiment/Kassiopeia/releases + +.. |Code Size| image:: https://img.shields.io/github/languages/code-size/KATRIN-Experiment/Kassiopeia + :target: https://github.com/KATRIN-Experiment/Kassiopeia + +.. |Issues github| image:: https://img.shields.io/github/issues/KATRIN-Experiment/Kassiopeia + :target: https://github.com/KATRIN-Experiment/Kassiopeia/issues + +.. |Pull Requests github| image:: https://img.shields.io/github/issues-pr/KATRIN-Experiment/Kassiopeia + :target: https://github.com/KATRIN-Experiment/Kassiopeia/pulls + +.. |Last Commit github| image:: https://img.shields.io/github/last-commit/KATRIN-Experiment/Kassiopeia + :target: https://github.com/KATRIN-Experiment/Kassiopeia/commits + +.. |Contributors github| image:: https://img.shields.io/github/contributors/KATRIN-Experiment/Kassiopeia + :target: https://github.com/KATRIN-Experiment/Kassiopeia/graphs/contributors + +.. |Gitter github| image:: https://badges.gitter.im/kassiopeia-simulation/community.svg + :target: https://gitter.im/kassiopeia-simulation/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge + +.. |Binder github| image:: https://mybinder.org/badge_logo.svg + :target: https://mybinder.org/v2/gh/KATRIN-Experiment/KassiopeiaBinder/HEAD + -Contents -======== +Welcome to Kassiopeia's documentation! +************************************** -.. toctree:: +.. dropdown:: **Documentation Contents** + + .. toctree:: :maxdepth: 4 Introduction @@ -28,8 +53,59 @@ Contents XML Bindings License Authors + + + + + + + + +This simulation package by `the KATRIN collaboration`_ allows to run highly customizable particle tracking simulations +along with calculations of electric and magnetic fields. + +.. _`the KATRIN collaboration`: https://katrin.kit.edu + +**Source Code:** https://github.com/KATRIN-Experiment/Kassiopeia + + +**Quick start:** |Try it out online|_ +in an interactive Binder session. Open a "VNC (Desktop)" tab and a terminal tab and run + + +.. |Try it out online| replace:: **Try it out online** +.. _Try it out online: https://mybinder.org/v2/gh/KATRIN-Experiment/KassiopeiaBinder/HEAD + + +.. code-block:: bash + + Kassiopeia $KASPERSYS/config/Kassiopeia/Examples/DipoleTrapSimulation.xml + + +to run your first simulation! *Note: A VTK error indicates that the "VNC (Desktop)" tab is not open yet.* + +**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) + + +**Docker images** +-------------- + +**All images:** https://github.com/orgs/KATRIN-Experiment/packages + +The `kassiopeia/full` image comes with a JupyterLab installation, can run on Kubernetes based JupyterHubs and is also used for the "try it out online" link above. + + +|More information|_ + +.. |More information| replace:: **More information** +.. _More information: https://github.com/KATRIN-Experiment/Kassiopeia/blob/main/Docker/README.md + -Indices and tables -================== -* :ref:`search` diff --git a/Documentation/gh-pages/source/introduction.rst b/Documentation/gh-pages/source/introduction.rst index 5b176a3da..100fe9304 100644 --- a/Documentation/gh-pages/source/introduction.rst +++ b/Documentation/gh-pages/source/introduction.rst @@ -17,7 +17,7 @@ The Kasper framework ==================== The *Kassiopeia* software relies upon three separate, but concurrently distributed libraries. These are *Kommon*, -*KGeoBag*, and *KEMField* and part of the **Kasper** framework. +*KGeoBag* and *KEMField*. * *Kommon* contains a collection of commonly used and very basic utilities which are used by the other three packages. It also contains a unique system for parsing and constructing objects from an XML file.