docs: add reproducibility tips for beginners

.gitattributes

@@ -11,7 +11,11 @@ pygimli/_version.py export-subst
 *.sh text
 
 # Declare files that will always have CRLF line endings on checkout.
-# *.sln text eol=crlf
+*.py text eol=crlf
+*.md text eol=crlf
+*.rst text eol=crlf
+*.bib text eol=crlf
+*.txt text eol=crlf
 
 # Denote all files that are truly binary and should not be modified.
 *.png binary

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,107 @@
+name: Bug Report
+description: Please use this form to file a bug report.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for taking the time to fill out this bug report! To facilitate efficient support, please fill out all the information applicable to your issue.
+  - type: markdown
+    attributes:
+      value: "### Problem description"
+  - type: textarea
+    id: problem-description
+    attributes:
+      label: Problem description
+      description: Please provide a general description of the issue here.
+  - type: markdown
+    attributes:
+      value: "### Your environment"
+  - type: textarea
+    id: environment-report
+    attributes:
+      label: Your environment
+      description: Please provide the output of `print(pygimli.Report())` here. If that does not work, please fill out the information on operating system, Python version and pyGIMLi version below.
+      render: shell
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      description: Which operating system are you using?
+      options:
+        - Windows
+        - Mac
+        - Linux
+  - type: dropdown
+    id: python-version
+    attributes:
+      label: Which Python version are you using?
+      options:
+        - 3.15
+        - 3.14
+        - 3.13
+        - 3.12
+        - 3.11
+        - 3.10
+        - 3.9
+  - type: input
+    id: way-of-installation
+    attributes:
+      label: Way of installation
+      description: Please describe your way of installing pyGIMLi, e.g. Conda package, manual compilation from source etc.
+  - type: dropdown
+    id: pygimli-version
+    attributes:
+      label: Which version of PyGIMLI are you using?
+      description: Output of `print(pygimli.__version__)`
+      options:
+        - 1.5.4
+        - 1.5.3
+        - 1.5.2
+        - 1.5.1
+        - 1.5.0
+  - type: textarea
+    id: environment-additional
+    attributes:
+      label: Additional information on the environment
+      description: If you have additional information on the environment or installation that did not fit the forms above, please enter it here.
+  - type: markdown
+    attributes:
+      value: "### Reproducing the issue"
+  - type: textarea
+    id: reproduce-steps
+    attributes:
+      label: Steps to reproduce the issue
+      description: If there are specific steps necessary to reproduce the issue, please describe them here.
+  - type: textarea
+    id: reproduce-code
+    attributes:
+      label: Code to reproduce the issue
+      description: Please provide the code that produces the error in the form of a minimal reproducible example. Alternatively, you can also attach the code as a file in the field below.
+      render: shell
+  - type: textarea
+    id: reproduce-data
+    attributes:
+      label: Additional data to reproduce the issue
+      description: Please provide additional data that is necessary to reproduce the error, e.g. data files, additional code or Python dependencies.
+  - type: markdown
+    attributes:
+      value: "### Expected behavior"
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: Tell us what should happen or what you want to achieve.
+  - type: markdown
+    attributes:
+      value: "### Actual behavior"
+  - type: textarea
+    id: actual-text
+    attributes:
+      label: Actual behavior
+      description: Please tell us what happens instead of the expected behavior.
+  - type: textarea
+    id: actual-output
+    attributes:
+      label: Output of your script
+      description: If applicable, please provide the output of your script that shows the actual behavior.
+      render: shell

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,9 @@
+name: Feature Request
+description: Please use this form to propose a new feature for pyGIMLi.
+labels: ["feature request"]
+body:
+- type: textarea
+  id: feature-request
+  attributes:
+    label: Feature Request
+    description: Please provide details on the feature request here.

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,9 @@
+name: Question
+description: Please use this form if you expect that your issue is rather a question than a problem with the code.
+labels: ["question"]
+body:
+- type: textarea
+  id: question
+  attributes:
+    label: Question
+    description: Please provide details on your issue or question.

.github/workflows/main.yml

@@ -60,25 +60,28 @@ jobs:
           working-directory: build
           run: xvfb-run make doc # xvfb is necessary for headless display of pyvista plots
   merging:
-    name: Merging dev into master
+    name: Automerging
     runs-on: self-hosted
     needs: docs
     if: github.ref == 'refs/heads/dev' # Only merge from dev
     steps:
-      - name: Merge into master
-        uses: devmasx/merge-branch@master
-        with:
-          type: now
-          target_branch: master
-          github_token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Merge dev -> master (with rebase)
+        working-directory: source
+        run: |
+          git config --local user.email "actions@github.com"
+          git config --local user.name "GitHub Actions"
+          git remote set-url origin https://florian-wagner:${{ secrets.SECRET }}@github.com/gimli-org/gimli.git
+          git fetch
+          git rebase origin/master
+          git push origin HEAD:master --force-with-lease
   upload-html:
     name: Upload HTML to dev.pygimli.org
     runs-on: self-hosted
     needs: docs
     if: github.ref == 'refs/heads/dev' # Only merge from dev
     steps:
-      - name: Merge into master
+      - name: Uploading built html files
         working-directory: build
         run: rsync -avP --delete doc/html/ /var/www/html
-        
-  
+
+

.gitignore

@@ -14,6 +14,9 @@ doc/_static/usecases/original/
 *.ipynb
 *.ipynb_checkpoints*
 
+doc/user-guide/*_files
+doc/user-guide/*.html
+
 # Customizations
 *.log
 *.pdf
@@ -110,4 +113,4 @@ pygimli/core/libgimli.dll.back
 pygimli/core/_pygimli_.pyd.back
 pygimli/core/_pygimli_.so.dSYM/
 pygimli/VERSION
-synth.ves
+synth.ves

.jenkins.sh

@@ -80,8 +80,8 @@ export PYVISTA_OFF_SCREEN=true
 export PYTHONPATH=`pwd`/../trunk:$PYTHONPATH
 OMP_THREAD_LIMIT=4 python -c "import pygimli; print(pygimli.Report()); pygimli.test(show=False, abort=True, htmlreport=\"build_tests.html\", devTests=True)"
 
-# Build documentation
-make clean-gallery
+#Build documentation
+#make clean-gallery # TMP for fast Jenkins builds
 make doc # = doxygen, sphinxapi, sphinxpdf, sphinxhtml
 end=$(date +"%s")
 echo "Ending automatic build #$BUILD_NUMBER".

AUTHORS.md

@@ -0,0 +1,17 @@
+- [Carsten Rücker](https://orcid.org/0000-0002-8231-9861)
+
+  *Berlin University of Technology, Department of Applied Geophysics, Berlin, Germany*
+
+  <carsten@pygimli.org>
+
+- [Thomas Günther](https://orcid.org/0000-0001-5409-0273)
+
+  *TU Bergakademie Freiberg, Electromagnetics and potential methods working group, Freiberg, Germany*
+
+  <thomas@pygimli.org>
+
+- [Florian Wagner](https://orcid.org/0000-0001-7407-9741)
+
+  *RWTH Aachen University, Geophysical Imaging and Monitoring (GIM), Aachen, Germany*
+
+  <florian@pygimli.org>

CITATION.md

@@ -0,0 +1,29 @@
+# Citing pyGIMLi
+
+If you use pyGIMLi for your work, please cite [this paper](http://www.sciencedirect.com/science/article/pii/S0098300417300584/pdfft?md5=44253eaacd5490e3fb32210671672496&pid=1-s2.0-S0098300417300584-main.pdf) as:
+
+> Rücker, C., Günther, T., Wagner, F.M., 2017. pyGIMLi: An open-source library
+> for modelling and inversion in geophysics, Computers and Geosciences, 109,
+> 106-123, doi: 10.1016/j.cageo.2017.07.011.
+
+```{raw} html
+<span class="__dimensions_badge_embed__" data-id="pub.1091104697" data-style="large_rectangle"></span><script async src="https://badge.dimensions.ai/badge.js" charset="utf-8"></script><br>
+```
+
+Scripts to reproduce the figures in the paper can be found at
+<https://cg17.pygimli.org>.
+
+BibTeX code:
+
+```bibtex
+@article{Ruecker2017,
+  title = {{pyGIMLi}: An open-source library for modelling and inversion in geophysics},
+  journal = {Computers and Geosciences},
+  volume = {109},
+  pages = {106--123},
+  year = {2017},
+  doi = {10.1016/j.cageo.2017.07.011},
+  url = {https://www.sciencedirect.com/science/article/pii/S0098300417300584},
+  author = {R\"ucker, C. and G\"unther, T. and Wagner, F. M.}
+}
+```

CMakeLists.txt

@@ -668,17 +668,6 @@ if (SPHINX_FOUND AND NOT SKIP_SPHINX)
     add_subdirectory(doc EXCLUDE_FROM_ALL)
     message(STATUS "Search recursive for related doc files from here: " ${CMAKE_SOURCE_DIR})
 
-    file(GLOB DOCFILES LIST_DIRECTORIES false
-            RELATIVE "${CMAKE_SOURCE_DIR}"
-        "*.rst")
-    message(STATUS "DOCFILES: " ${DOCFILES})
-
-    file(GLOB DFILES LIST_DIRECTORIES false
-            RELATIVE "${CMAKE_SOURCE_DIR}"
-        "*.md")
-    message(STATUS "MDFILES: " ${DFILES})
-    list(APPEND DOCFILES ${DFILES})
-
     set (RECDOCTYPES "*.rst" "*.md" "*.png" "*.svg" "*.bib" "paper/*.py")
 
     foreach (DTYPE ${RECDOCTYPES})
@@ -689,27 +678,6 @@ if (SPHINX_FOUND AND NOT SKIP_SPHINX)
         message(STATUS "Append DOC files: (${DTYPE}) " ${DFILES})
         list(APPEND DOCFILES ${DFILES})
     endforeach()
-    # message(STATUS "RSTFILES: " ${DFILES})
-
-    # file(GLOB_RECURSE DFILES LIST_DIRECTORIES false
-    # RELATIVE "${CMAKE_SOURCE_DIR}" "${CMAKE_SOURCE_DIR}" "./doc/*.md")
-    # message(STATUS "MDFILES: " ${DFILES})
-    # list(APPEND DOCFILES ${DFILES})
-
-    # file(GLOB_RECURSE DFILES LIST_DIRECTORIES false
-    # RELATIVE "${CMAKE_SOURCE_DIR}" "${CMAKE_SOURCE_DIR}" "./doc/*.png")
-    # message(STATUS "PNGFILES: " ${DFILES})
-    # list(APPEND DOCFILES ${DFILES})
-
-    # file(GLOB_RECURSE DFILES LIST_DIRECTORIES false
-    # RELATIVE "${CMAKE_SOURCE_DIR}" "${CMAKE_SOURCE_DIR}" "./doc/*.bib")
-    # message(STATUS "BIBFILES: " ${DFILES})
-    # list(APPEND DOCFILES ${DFILES})
-
-    # file(GLOB_RECURSE PYFILES LIST_DIRECTORIES false
-    #     RELATIVE "${CMAKE_SOURCE_DIR}" "${CMAKE_SOURCE_DIR}" "doc/paper/*.py")
-    # message(STATUS "PYFILES: " ${PYFILES})
-    # list(APPEND DOCFILES ${PYFILES})
 
     set(RSTFILES ${DOCFILES} CACHE INTERNAL "RST source file that we need to copy")