Reorder and update installation instructions

.github/workflows/runTestSinglePython.yml

@@ -6,8 +6,12 @@ name: Test single python version
 on:
   push:
     branches: [ master ]
+    paths-ignore:
+          - 'docs/**'
   pull_request:
     branches: [ master ]
+    paths-ignore:
+          - 'docs/**'
   workflow_dispatch:
 
 jobs:

docs/advancedUsage.rst

@@ -0,0 +1,71 @@
+Advanced Usage (Script)
+=======================
+
+After the installation, the next sections describe on how to get started. The sections configuration and logging
+describe the general methods we use, this is helpful to understand how you can change model parameters and similar. 
+
+.. include:: developinstall.rst
+
+--------------------------
+
+.. include:: gettingstarted.rst
+
+---------------------------
+
+.. include:: configuration.rst
+
+-------------------------
+
+.. include:: logging.rst
+
+-------------------------
+
+Example runscripts
+------------------
+
+In :py:mod:`runScripts` we provide ready-to-use scripts for different applications of the modules provided within
+AvaFrame.
+
+
+Derive input data
+^^^^^^^^^^^^^^^^^^^
+- :py:mod:`runScripts.runComputeDist`
+
+Create a new project
+^^^^^^^^^^^^^^^^^^^^^^
+- :py:mod:`runScripts.runInitializeProject`
+
+
+Generate idealized/generic topography data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- :py:mod:`runScripts.runGenerateTopo`
+- :py:mod:`runScripts.runGenProjTopoRelease`
+
+
+Postprocessing
+^^^^^^^^^^^^^^^
+
+- :py:mod:`runScripts.runAna3AIMEC`
+- :py:mod:`runScripts.runAna3AIMECCompMods`
+- :py:mod:`runScripts.runAna3AIMECIndi`
+- :py:mod:`runScripts.runStatsExample`
+- :py:mod:`runScripts.runProbAna`
+
+
+Visualisation
+^^^^^^^^^^^^^^^
+- :py:mod:`runScripts.runQuickPlotSimple`
+- :py:mod:`runScripts.runQuickPlotOne`
+- :py:mod:`runScripts.runPlotTopo`
+- :py:mod:`runScripts.runExportToCsv`
+
+
+Testing
+^^^^^^^^
+- :py:mod:`runScripts.runDamBreak`
+- :py:mod:`runScripts.runSimilaritySol`
+- :py:mod:`runScripts.runTestFP`
+- :py:mod:`runScripts.runStandardTestsCom1DFAOrig`
+- :py:mod:`runScripts.runComparisonModules`
+- :py:mod:`runScripts.runFetchBench`
+- :py:mod:`runScripts.runWriteDesDict`

docs/com1DFAAlgorithm.rst

@@ -1,5 +1,5 @@
-Dense Flow Avalanche algorithm and workflow
-============================================
+com1DFA Algorithm and workflow
+==============================
 
 Algorithm graph
 ----------------
@@ -293,7 +293,7 @@ The mesh values are updated with the particles properties using
 This is used to compute flow thickness, flow velocity and pressure fields from the particle properties.
 
 Update particles flow thickness
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The mesh flow thickness is finally used to update the particle flow thickness value
 using :ref:`mesh to particle interpolation <DFAnumerics:Mesh to particle>` methods.
 

docs/connector.rst

@@ -0,0 +1,50 @@
+AvaFrameConnector (GUI)
+=======================
+
+The AvaFrameConnector allows QGis users to access certain base workflows directly from QGis. The connector 
+only provides the interface to functions within the AvaFrame python package, and is developed separately, see the
+`QGisAF github repository <https://github.com/avaframe/QGisAF>`_. 
+It makes use of the QGis processing plugin, which is included in all current QGis releases. 
+
+Here is a quick overview of the processing scripts the AvaFrameConnector provides:
+
+Operational
+-----------
+
+.. glossary::
+   :sorted:
+
+   Dense Flow Standard 
+      Runs dense flow avalanche module com1DFA. For more specific info about the inputs (shapefile attributes etc), see 
+      :ref:`moduleCom1DFA:Input`. You can select multiple shapefiles for release areas, each will be calculated as one scenario. 
+      Each shapefile can contain multiple polygons. If you provide entrainment/resistance areas, each scenario will be calculated 
+      once without them (i.e null simulation) and once with them. 
+
+   Full Operational Run
+      Runs com1DFA and additionally com2AB if profile and splitpoint are set. 
+      Additional info see description of runCom1DFA. 
+
+
+Experimental
+------------
+
+These either require deeper knowledge about the AvaFrame python package, i.e. configuration files etc., or are not yet 
+fully tested and might produce unwanted results. 
+
+.. glossary::
+   :sorted:
+
+   AvaFrameLayerRename   
+      Renames com1DFA result layers by adding the values of the given variable (from the configuration file) 
+
+Admin
+-----
+
+.. glossary::
+   :sorted:
+
+   GetVersion 
+      Displays the current version of the AvaFrame python package (NOT the AvaFrameConnector)
+
+   UpdateAvaFrame
+      Updates the AvaFrame python package

docs/develop.rst

@@ -1,5 +1,9 @@
-Notes to Developers 
-===================
+Development
+===========
+
+
+Notes to developers
+-------------------
 
 Here you can find notes on design principles and how to contribute to AvaFrame.
 
@@ -32,7 +36,7 @@ AF-STYLE-4: No dead code
   reading the source code. Old code is available in the source history if
   it is needed.
 
-
+--------------------------
 
 Our suggested git workflow
 --------------------------
@@ -88,6 +92,9 @@ repository/origin will be handled by the pull request)::
   git branch -d myAwesomeFeature
 
 
+--------------------------
+
+
 Build the documentation
 ------------------------
 
@@ -127,6 +134,7 @@ and you should see something like::
 
   ==========================1 passed in 0.02s =========================
 
+---------------------------
 
 How to add a benchmark test
 ----------------------------
@@ -163,52 +171,3 @@ You can check out the markdown-style report of the comparison at:
 ``tests/reports/standardTestsReportPy.md``.
 
 
-Examples
----------
-
-In :py:mod:`runScripts` we provide ready-to-use scripts for different applications of the modules provided within
-AvaFrame.
-
-
-Derive input data
-~~~~~~~~~~~~~~~~~~~
-- :py:mod:`runScripts.runComputeDist`
-
-Create a new project
-~~~~~~~~~~~~~~~~~~~~~~
-- :py:mod:`runScripts.runInitializeProject`
-
-
-Generate idealized/generic topography data
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- :py:mod:`runScripts.runGenerateTopo`
-- :py:mod:`runScripts.runGenProjTopoRelease`
-
-
-Postprocessing
-~~~~~~~~~~~~~~~
-
-- :py:mod:`runScripts.runAna3AIMEC`
-- :py:mod:`runScripts.runAna3AIMECCompMods`
-- :py:mod:`runScripts.runAna3AIMECIndi`
-- :py:mod:`runScripts.runStatsExample`
-- :py:mod:`runScripts.runProbAna`
-
-
-Visualisation
-~~~~~~~~~~~~~~~
-- :py:mod:`runScripts.runQuickPlotSimple`
-- :py:mod:`runScripts.runQuickPlotOne`
-- :py:mod:`runScripts.runPlotTopo`
-- :py:mod:`runScripts.runExportToCsv`
-
-
-Testing
-~~~~~~~~
-- :py:mod:`runScripts.runDamBreak`
-- :py:mod:`runScripts.runSimilaritySol`
-- :py:mod:`runScripts.runTestFP`
-- :py:mod:`runScripts.runStandardTestsCom1DFAOrig`
-- :py:mod:`runScripts.runComparisonModules`
-- :py:mod:`runScripts.runFetchBench`
-- :py:mod:`runScripts.runWriteDesDict`

docs/developinstall.rst

@@ -1,9 +1,9 @@
-Development Installation 
-------------------------
+Advanced (Script) Installation 
+------------------------------
 
 This is a quick guide on how to install AvaFrame
 and the required dependencies on your machine. AvaFrame is developed on **Linux
-machines** (Ubuntu/Manjaro/Arch) with recent Python versions 3.8/3.9.
+machines** (Ubuntu/Manjaro/Arch) with recent Python versions > 3.8.
 These instructions assume you are familiar with working in a terminal. This
 guide is currently described for *Linux* only, but expert users should be able
 to adapt it to *Windows*.
@@ -24,7 +24,7 @@ Setup AvaFrame
 
 Create a new `conda environment
 <https://conda.io/projects/conda/en/latest/user-guide/concepts/environments.html>`_
-for AvaFrame, activate it and install pip in this environment::
+for AvaFrame, activate it and install pip, numpy and cython in this environment::
 
   conda create --name avaframe_env
   conda activate avaframe_env
@@ -55,7 +55,7 @@ current (local) version will be used.
 Test it by starting ``python`` and do an ``import avaframe``. If no error comes
 up, you are good to go.
 
-Head over to :ref:`gettingstarted:Getting Started` for the next steps.
+Head over to :ref:`gettingstarted:First run` for the next steps.
 
 Update AvaFrame
 ^^^^^^^^^^^^^^^

docs/gettingstarted.rst

@@ -1,14 +1,12 @@
-Basic usage
-===========
+.. Basic usage
+.. -----------
 
-.. Note::
+.. .. Note::
 
-   These instructions target the development installation. If you are using the standard / operational installation we
-   provide a recording from the first public `AvaFrame workshop <https://youtu.be/HOFygSkCmp0>`_ . You will find a demo
-   starting at around the 17:25min mark.  
+   .. These instructions target the development installation. If you are using the standard / operational installation we
+   .. provide a recording from the first public `AvaFrame workshop <https://youtu.be/HOFygSkCmp0>`_ . You will find a demo
+   .. starting at around the 17:25min mark.  
 
-After the installation, the next sections describe on how to get started. The sections configuration and logging
-describe the general methods we use, this is helpful to understand how you can change model parameters and similar. 
 
 First run
 ---------
@@ -53,7 +51,7 @@ Workflow example
 
 The following example should make it easier for you to find your way in AvaFrame and setup your own AvaFrame workflow
 after you did the full setup. There is also a directory with examples for different workflows, see more here:
-:ref:`develop:Examples`.
+:ref:`advancedUsage:Example runScripts`.
 
 Make sure you change to your ``AvaFrame`` directory by::
 
@@ -105,9 +103,5 @@ template.
 We suggest you copy it and adjust it to your liking. There are annotations in
 the code that should help you to understand the structure.
 
-A lot more examples can be found in the ``runScripts`` directory (see also :ref:`develop:Examples`).
+A lot more examples can be found in the ``runScripts`` directory (see also :ref:`advancedUsage:Example runscripts`).
 
-
-.. include:: configuration.rst
-
-.. include:: logging.rst

docs/index.rst

@@ -15,10 +15,8 @@ General
 
     * :doc:`introduction`
     * :doc:`installation`
-    * :doc:`operational`
-    * :doc:`operationalGerman`
-    * :doc:`developinstall`
-    * :doc:`gettingstarted`
+    * :doc:`connector`
+    * :doc:`advancedUsage`
     * :doc:`testing`
     * :doc:`Visualisation`
     * :doc:`FAQ`
@@ -27,16 +25,14 @@ General
     * :doc:`develop`
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 4
    :hidden:
    :caption: General
 
    introduction.rst
    installation.rst
-   operational.rst
-   operationalGerman.rst
-   developinstall.rst
-   gettingstarted.rst
+   connector.rst
+   advancedUsage.rst
    testing.rst
    Visualisation.rst
    FAQ.rst