build HTML docs at package build time and open them from the Help menu

- debian/rules: build sphinx HTML into build/html
- debian/install: install it as usr/share/doc/python3-damaris/html/
  instead of shipping the raw doc/ source tree (whose gitignored
  doc/_build never existed on CI checkouts)
- debian/control: declare ${sphinxdoc:Depends} and python3-sphinx
  (provides sphinx-build) explicitly
- requirements.debian: install python3-sphinx explicitly
- DamarisGUI: point the manual at the packaged HTML path with a
  source-tree fallback, populate the Help dropdown menu, and open
  the DAMARIS manual on a plain toolbar click
- doc/manual.rst: document the Help menu

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>

debian/control

@@ -2,7 +2,7 @@ Source: python3-damaris
 Section: science
 Priority: optional
 Maintainer: Markus Rosenstihl <markus.rosenstihl@pkm.tu-darmstadt.de>
-Build-Depends: python3, debhelper, python3-dev, dh-sequence-python3, dpkg-dev, pybuild-plugin-pyproject, sphinx-common, sphinx-rtd-theme-common, python3-sphinxcontrib.bibtex, python3-sphinx-rtd-theme
+Build-Depends: python3, debhelper, python3-dev, dh-sequence-python3, dpkg-dev, pybuild-plugin-pyproject, sphinx-common, python3-sphinx, sphinx-rtd-theme-common, python3-sphinxcontrib.bibtex, python3-sphinx-rtd-theme
 Standards-Version: 3.7.3
 X-Python3-Version: >= 3.5
 Rules-Requires-Root: no
@@ -10,7 +10,7 @@ Rules-Requires-Root: no
 Package: python3-damaris
 Architecture: all
 Provides: damaris-frontend-py3
-Depends: ${python3:Depends}, python3-numpy, python3-scipy, python3-gi, python3-matplotlib, python3-tables, lzop, python3-xdg, libgtksourceview-3.0-1, libgirepository1.0-dev | libgirepository-2.0-dev, breeze-icon-theme
+Depends: ${python3:Depends}, ${sphinxdoc:Depends}, python3-numpy, python3-scipy, python3-gi, python3-matplotlib, python3-tables, lzop, python3-xdg, libgtksourceview-3.0-1, libgirepository1.0-dev | libgirepository-2.0-dev, breeze-icon-theme
 Recommends: damaris-backends, python3-numpy-ext
 Suggests: python3-doc, python3-tables-doc, python3-numpy-doc
 Description: python frontend for DAMARIS project

debian/install

@@ -1,4 +1,4 @@
-doc/ usr/share/doc/python3-damaris/
+build/html usr/share/doc/python3-damaris/
 debian/damaris3.desktop usr/share/applications/
 src/damaris/gui/DAMARIS3.png usr/share/pixmaps/
 src/damaris/gui/DAMARIS3.ico usr/share/pixmaps/

debian/rules

@@ -17,7 +17,7 @@ DH_ALWAYS_EXCLUDE=CVS:.git:venv:.venv:*.h5
 
 override_dh_auto_build:
 	dh_auto_build
-	sphinx-build -N -bhtml doc/ build/doc
+	sphinx-build -N -bhtml doc/ build/html
 
 
 override_dh_auto_test:

doc/manual.rst

@@ -101,6 +101,12 @@ There are now two possibilities to export the figure:
 2. Saving the data of the plot as CSV file (comma separated values) by pressing the button on the right side of the toolbar under the plot
 
 
+Help Menu
+=========
+
+The **Help** button in the toolbar opens this documentation in the system's web browser. The arrow next to it offers additional local documentations, such as the Python documentation, if installed. When the Debian package is used, the HTML documentation is found in ``/usr/share/doc/python3-damaris/html/``.
+
+
 Accumulation
 ============
 

requirements.debian

@@ -1,7 +1,7 @@
 #!/bin/bash
 apt-get -y install libcairo2-dev gir1.2-gtksource-3.0 hdf5-tools
 apt-get -y install python3-dev python3-scipy python3-lmfit python3-matplotlib python3-tables python3-xdg  python3-setuptools python3-sphinx-rtd-theme
-apt-get -y install debhelper dh-sequence-python3 lsb-release sphinx-common pybuild-plugin-pyproject python3-sphinxcontrib.bibtex
+apt-get -y install debhelper dh-sequence-python3 lsb-release sphinx-common python3-sphinx pybuild-plugin-pyproject python3-sphinxcontrib.bibtex
 DEBRELEASE=$(lsb_release -cs)
 case $DEBRELEASE in
   "trixie")

src/damaris/gui/DamarisGUI.py

@@ -1276,15 +1276,31 @@ class DamarisGUI:
 
     def documentation_init( self ):
 
-        self.doc_urls = {
+        doc_index_candidates = (
-            "DAMARIS Manual": "file:///usr/share/doc/python3-damaris/doc/_build/html/index.html",
+            "/usr/share/doc/python3-damaris/html/index.html",
-        }
+            os.path.join( os.path.dirname( os.path.dirname( os.path.dirname(
+                os.path.dirname( os.path.abspath( __file__ ) ) ) ) ),
+                "doc", "_build", "html", "index.html" ),
+        )
+
+        self.doc_urls = { }
+        for doc_index in doc_index_candidates:
+            if os.path.isfile( doc_index ):
+                self.doc_urls[ "DAMARIS Manual" ] = "file://" + doc_index
+                break
 
         if os.path.isdir( "/usr/share/doc/python%d.%d-doc/html" % (sys.version_info[ :2 ]) ):
             self.doc_urls[ "Python Docs" ] = "file:///usr/share/doc/python%d.%d-doc/html/index.html" % (
             sys.version_info[ :2 ])
 
-        doc_index_url = None
+        doc_menu = self.xml_gui.get_object( "documentation_menu" )
+        for doc_title in self.doc_urls:
+            doc_menu_item = gtk.MenuItem( label=doc_title )
+            doc_menu_item.connect( "activate", self.show_doc_menu )
+            doc_menu.append( doc_menu_item )
+            doc_menu_item.show( )
+        self.xml_gui.get_object( "documentation" ).set_menu( doc_menu )
+
         self.doc_browser = None
 
     def show_doc_menu( self, widget, data=None ):
@@ -1294,7 +1310,7 @@ class DamarisGUI:
         if type( widget ) is gtk.MenuItem:
             requested_doc = widget.get_child( ).get_text( )
         else:
-            requested_doc = "Python DAMARIS"
+            requested_doc = "DAMARIS Manual"
 
         if requested_doc in self.doc_urls and self.doc_urls[ requested_doc ] is not None:
             if self.doc_browser is not None: