Added help to the GUI client

git-svn-id: https://linkchecker.svn.sourceforge.net/svnroot/linkchecker/trunk/linkchecker@3964 e7d03fd6-7b0d-0410-9947-9c21f3af8025

TODO.txt

@@ -1,3 +1,2 @@
 - [GUI] Store checked links in urldata list; display in a QTreeWidget;
   columns result (as icon), URL, name; doubleclick opens property popup
-- [GUI] Integrate sphinx documentation

doc/Makefile

@@ -11,17 +11,52 @@ PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-.PHONY: help clean html web pickle htmlhelp latex changes linkcheck homepage test po4a api
+.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
 
-all: clean html compress
+all:
+	@echo "Available targets: build-html build-htmlhelp"
+
+build-html:	clean html
+
+build-htmlhelp:	clean htmlhelp helpfiles
 
 html:
 	mkdir -p build/html build/doctrees
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
-	rm build/html/_static/Makefile build/html/_static/favicon*.png
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/html
+	rm build/html/_static/Makefile
+	rm build/html/_static/default.css
+	rm build/html/_static/*.js
+	rm build/html/_static/contents.png
+	rm build/html/_static/plus.png
+	rm build/html/_static/file.png
+	rm build/html/_static/minus.png
+	rm build/html/_static/navigation.png
+	rm build/html/_static/rightsidebar.css
+	rm build/html/_static/stickysidebar.css
+	rm build/html/_static/sphinxdoc.css
+	rm build/html/_static/traditional.css
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."
 
+htmlhelp:
+	mkdir -p build/htmlhelp build/doctrees
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
+	rm build/htmlhelp/LinkChecker*
+	rm build/htmlhelp/_static/Makefile
+	rm build/htmlhelp/_static/default.css
+	rm build/htmlhelp/_static/*.js
+	rm build/htmlhelp/_static/contents.png
+	rm build/htmlhelp/_static/plus.png
+	rm build/htmlhelp/_static/file.png
+	rm build/htmlhelp/_static/minus.png
+	rm build/htmlhelp/_static/navigation.png
+	rm build/htmlhelp/_static/rightsidebar.css
+	rm build/htmlhelp/_static/stickysidebar.css
+	rm build/htmlhelp/_static/sphinxdoc.css
+	rm build/htmlhelp/_static/traditional.css
+	@echo
+	@echo "Build finished. The HTML pages are in build/htmlhelp."
+
 pickle:
 	mkdir -p build/pickle build/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
@@ -36,13 +71,6 @@ json:
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp:
-	mkdir -p build/htmlhelp build/doctrees
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in build/htmlhelp."
-
 latex:
 	mkdir -p build/latex build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
@@ -66,24 +94,33 @@ linkcheck:
 
 clean:
 	-rm -rf build/*
-
-homepage:	clean html compress
-	cp -r build/html/* $(HOME)/public_html/linkchecker.sf.net/htdocs
+	-rm -f *.qhc *.qch
 
 test:	html
 	xmllint --valid --noout build/html/*.html
 
-po4a:
-	po4a --localized-charset=UTF-8 po4a.conf
-
-api:
-	epydoc --html -o api --name "LinkChecker source documentation" --url ../index.html ../linkcheck/
-
-
 YUICOMP_VERSION=2.4.2
 YUICOMP=$(HOME)/src/yuicompressor-$(YUICOMP_VERSION)/build
 
 compress:
 	python mediacompress.py --overwrite=png,jpg,gif,js,css \
 	  --js-compressor=$(YUICOMP)/yuicompressor-$(YUICOMP_VERSION).jar \
-	  build/html
+	  build
+
+
+HELPFILES = lccollection.qhc
+
+helpfiles: $(HELPFILES)
+
+%.qhc:	%.qhcp lcdoc.qhp
+	qcollectiongenerator $< -o $@
+
+
+homepage:	build-html compress
+	cp -r build/html/* $(HOME)/public_html/linkchecker.sf.net/htdocs
+
+po4a:
+	po4a --localized-charset=UTF-8 po4a.conf
+
+api:
+	epydoc --html -o api --name "LinkChecker source documentation" --url ../index.html ../linkcheck/

doc/lccollection.qhcp

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<QHelpCollectionProject version="1.0">
+<assistant>
+   <title>LinkChecker</title>
+   <applicationIcon>build/htmlhelp/_static/favicon16x16.png</applicationIcon>
+   <cacheDirectory>bfk/LinkChecker</cacheDirectory>
+   <startPage>qthelp://bfk.app.linkchecker/doc/documentation.html</startPage>
+   <enableDocumentationManager>false</enableDocumentationManager>
+   <enableAddressBar>false</enableAddressBar>
+   <enableFilterFunctionality>false</enableFilterFunctionality>
+</assistant>
+<docFiles>
+  <generate>
+    <file>
+      <input>lcdoc.qhp</input>
+      <output>lcdoc.qch</output>
+    </file>
+  </generate>
+  <register>
+    <file>lcdoc.qch</file>
+  </register>
+</docFiles>
+</QHelpCollectionProject>

doc/lcdoc.qhp

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<QtHelpProject version="1.0">
+  <namespace>bfk.app.linkchecker</namespace>
+  <virtualFolder>doc</virtualFolder>
+  <filterSection>
+    <toc>
+      <section title="LinkChecker Application Manual" ref="build/htmlhelp/documentation.html" />
+    </toc>
+    <files>
+      <file>build/htmlhelp/documentation.html</file>
+    </files>
+  </filterSection>
+</QtHelpProject>

linkcheck/gui/__init__.py

@@ -16,13 +16,14 @@
 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 
 import os
-from PyQt4 import QtCore, QtGui
+from PyQt4 import QtCore, QtGui, QtHelp
 from .linkchecker_ui_main import Ui_MainWindow
 from .linkchecker_ui_options import Ui_Options
 from .. import configuration, checker, director, add_intern_pattern, \
     strformat
 from ..containers import enum
 
+DocBaseUrl = "qthelp://bfk.app.linkchecker/doc/build/htmlhelp/"
 
 Status = enum('idle', 'checking', 'stopping')
 
@@ -40,15 +41,14 @@ class LinkCheckerMain (QtGui.QMainWindow, Ui_MainWindow):
         else:
             self.output.setFontFamily("mono")
         self.checker = Checker()
-
         settings = QtCore.QSettings('bfk', configuration.AppName)
         settings.beginGroup('mainwindow')
-
         if settings.contains('size'):
             self.resize(settings.value('size').toSize())
             self.move(settings.value('pos').toPoint())
         settings.endGroup()
-
+        # Note: we can't use QT assistant here because of the .exe packaging
+        self.assistant = HelpWindow(self, "doc/lccollection.qhc")
         self.connect(self.checker, QtCore.SIGNAL("finished()"), self.set_status_idle)
         self.connect(self.checker, QtCore.SIGNAL("terminated()"), self.set_status_idle)
         self.connect(self.checker, QtCore.SIGNAL("add_message(QString)"), self.add_message)
@@ -57,6 +57,7 @@ class LinkCheckerMain (QtGui.QMainWindow, Ui_MainWindow):
         self.connect(self.optionsButton, QtCore.SIGNAL("clicked()"), self.options.exec_)
         self.connect(self.actionQuit, QtCore.SIGNAL("triggered()"), self.close)
         self.connect(self.actionAbout, QtCore.SIGNAL("triggered()"), self.about)
+        self.connect(self.actionHelp, QtCore.SIGNAL("triggered()"), self.showDocumentation)
         self.status = Status.idle
 
     def get_status (self):
@@ -94,6 +95,11 @@ class LinkCheckerMain (QtGui.QMainWindow, Ui_MainWindow):
         """Set idle status. Helper function for signal connections."""
         self.status = Status.idle
 
+    def showDocumentation (self):
+        """Show help page."""
+        url = QtCore.QUrl("%sindex.html" % DocBaseUrl)
+        self.assistant.showDocumentation(url)
+
     def closeEvent (self, e=None):
         """Save settings on close."""
         settings = QtCore.QSettings('bfk', configuration.AppName)
@@ -187,6 +193,63 @@ Version 2 or later.</p>
         self.statusBar.showMessage(msg)
 
 
+class HelpWindow (QtGui.QDialog):
+    """A custom help display dialog."""
+
+    def __init__ (self, parent, qhcpath):
+        """Initialize dialog and load qhc help project from given path."""
+        super(HelpWindow, self).__init__(parent)
+        self.engine = QtHelp.QHelpEngine(qhcpath, self)
+        self.engine.setupData()
+        self.setWindowTitle(u"%s Help" % configuration.AppName)
+        self.build_ui()
+
+    def build_ui (self):
+        """Build UI for the help window."""
+        splitter = QtGui.QSplitter()
+        splitter.setOrientation(QtCore.Qt.Vertical)
+        self.browser = HelpBrowser(splitter, self.engine)
+        tree = self.engine.contentWidget()
+        tree.setExpandsOnDoubleClick(False)
+        splitter.addWidget(tree)
+        splitter.addWidget(self.browser)
+        splitter.setSizes((70, 530))
+        hlayout = QtGui.QHBoxLayout()
+        hlayout.addWidget(splitter)
+        self.setLayout(hlayout)
+        self.resize(800, 600)
+        self.connect(self.engine.contentWidget(),
+            QtCore.SIGNAL("linkActivated(QUrl)"),
+            self.browser, QtCore.SLOT("setSource(QUrl)"))
+
+    def showDocumentation (self, url):
+        """Show given URL in help browser."""
+        self.browser.setSource(url)
+        self.show()
+
+
+class HelpBrowser (QtGui.QTextBrowser):
+    """A QTextBrowser that can handle qthelp:// URLs."""
+
+    def __init__ (self, parent, engine):
+        """Initialize and store given HelpEngine instance."""
+        super(HelpBrowser, self).__init__(parent)
+        self.engine = engine
+
+    def setSource (self, url):
+        if url.scheme() == "http":
+            import webbrowser
+            webbrowser.open(str(url.toString()))
+        else:
+            QtGui.QTextBrowser.setSource(self, url)
+
+    def loadResource (self, rtype, url):
+        """Handle qthelp:// URLs, load content from help engine."""
+        if url.scheme() == "qthelp":
+            return QtCore.QVariant(self.engine.fileData(url))
+        return QtGui.QTextBrowser.loadResource(self, rtype, url)
+
+
 class LinkCheckerOptions (QtGui.QDialog, Ui_Options):
     """Hold options for current URL to check."""
 

linkcheck/gui/linkchecker_ui_main.py

@@ -2,7 +2,7 @@
 
 # Form implementation generated from reading ui file 'ui/main.ui'
 #
-# Created: Sat Jan 24 19:15:50 2009
+# Created: Wed Feb 18 19:58:39 2009
 #      by: PyQt4 UI code generator 4.4.4
 #
 # WARNING! All changes made in this file will be lost!
@@ -72,8 +72,11 @@ class Ui_MainWindow(object):
         self.actionQuit.setObjectName("actionQuit")
         self.actionAbout = QtGui.QAction(MainWindow)
         self.actionAbout.setObjectName("actionAbout")
+        self.actionHelp = QtGui.QAction(MainWindow)
+        self.actionHelp.setObjectName("actionHelp")
         self.menuLinkChecka.addAction(self.actionQuit)
         self.menuHelp.addAction(self.actionAbout)
+        self.menuHelp.addAction(self.actionHelp)
         self.menubar.addAction(self.menuLinkChecka.menuAction())
         self.menubar.addAction(self.menuHelp.menuAction())
         self.label.setBuddy(self.urlinput)
@@ -91,5 +94,6 @@ class Ui_MainWindow(object):
         self.menuHelp.setTitle(QtGui.QApplication.translate("MainWindow", "Help", None, QtGui.QApplication.UnicodeUTF8))
         self.actionQuit.setText(QtGui.QApplication.translate("MainWindow", "Quit", None, QtGui.QApplication.UnicodeUTF8))
         self.actionAbout.setText(QtGui.QApplication.translate("MainWindow", "About", None, QtGui.QApplication.UnicodeUTF8))
+        self.actionHelp.setText(QtGui.QApplication.translate("MainWindow", "Help", None, QtGui.QApplication.UnicodeUTF8))
 
 import linkchecker_rc

linkcheck/gui/ui/main.ui

@@ -123,6 +123,7 @@
      <string>Help</string>
     </property>
     <addaction name="actionAbout" />
+    <addaction name="actionHelp" />
    </widget>
    <addaction name="menuLinkChecka" />
    <addaction name="menuHelp" />
@@ -138,6 +139,11 @@
     <string>About</string>
    </property>
   </action>
+  <action name="actionHelp" >
+   <property name="text" >
+    <string>Help</string>
+   </property>
+  </action>
  </widget>
  <resources>
   <include location="../rc/linkchecker.qrc" />