From 9cc449d6e1b756f88ad68438d7ba373e8926d21d Mon Sep 17 00:00:00 2001 From: Markus Rosenstihl Date: Sun, 18 Oct 2026 17:20:33 +0200 Subject: [PATCH] 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 --- debian/control | 4 ++-- debian/install | 2 +- debian/rules | 2 +- doc/manual.rst | 6 ++++++ requirements.debian | 2 +- src/damaris/gui/DamarisGUI.py | 26 +++++++++++++++++++++----- 6 files changed, 32 insertions(+), 10 deletions(-) diff --git a/debian/control b/debian/control index dfd09e4..8d04745 100644 --- a/debian/control +++ b/debian/control @@ -2,7 +2,7 @@ Source: python3-damaris Section: science Priority: optional Maintainer: Markus Rosenstihl -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 diff --git a/debian/install b/debian/install index 0213823..74eef99 100644 --- a/debian/install +++ b/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/ diff --git a/debian/rules b/debian/rules index 9f25e53..0d881ec 100755 --- a/debian/rules +++ b/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: diff --git a/doc/manual.rst b/doc/manual.rst index 03c15ac..a9d0ed7 100644 --- a/doc/manual.rst +++ b/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 ============ diff --git a/requirements.debian b/requirements.debian index 9cbbe4b..35763e4 100644 --- a/requirements.debian +++ b/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") diff --git a/src/damaris/gui/DamarisGUI.py b/src/damaris/gui/DamarisGUI.py index 39cc7b9..b9716e7 100644 --- a/src/damaris/gui/DamarisGUI.py +++ b/src/damaris/gui/DamarisGUI.py @@ -1276,15 +1276,31 @@ class DamarisGUI: def documentation_init( self ): - self.doc_urls = { - "DAMARIS Manual": "file:///usr/share/doc/python3-damaris/doc/_build/html/index.html", - } + doc_index_candidates = ( + "/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: