Merge pull request #308 from endlessm/issues/302

Documentation for WebHelper

6 files changed, 224 insertions, 14 deletions

diff --git a/.gitignore b/.gitignore
index 0cf83de..9a9dbe4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,7 @@ endless/eosresource-private.h
 data/eos-wikipedia-domain.gresource
 wikipedia/config.js
 tools/eos-run-test
+docs/reference/webhelper/eos.css
 
 *.py[cod]
 
@@ -133,3 +134,10 @@ nosetests.xml
 # Editor stuff
 *~
 *.swp
+
+# NaturalDocs project files
+/docs/reference/webhelper/Data/
+/docs/reference/webhelper/Languages.txt
+/docs/reference/webhelper/Menu.txt
+/docs/reference/webhelper/Topics.txt
+/docs/reference/webhelper/html/
diff --git a/Makefile.am b/Makefile.am
index b856f5d..013493e 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -23,7 +23,7 @@ AM_CFLAGS = @STRICT_CFLAGS@
 
 # Make sure to run Gtk-doc tests and build the documentation when doing
 # 'make distcheck'
-DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc --enable-gir-doc
+DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc --enable-gir-doc --enable-js-doc
 
 # Generated files that 'make clean' should erase
 CLEANFILES =
@@ -35,8 +35,8 @@ dist-hook:
 else
 dist-hook:
 	@echo "***"
-	@echo "*** You must configure with --enable-gtk-doc and --enable-gir-doc"
-	@echo "*** to run make dist or make distcheck."
+	@echo "*** You must configure with --enable-gtk-doc, --enable-gir-doc, and"
+	@echo "*** --enable-js-doc to run make dist or make distcheck."
 	@echo "***"
 	@false
 endif
@@ -123,6 +123,10 @@ CLEANFILES += \
 	docs/reference/endless-js/html/*.js
 endif
 
+# # # PURE JAVASCRIPT MODULE DOCUMENTATION # # #
+
+include $(top_srcdir)/docs/reference/webhelper/Makefile.am.inc
+
 # # # SECONDARY GRESOURCES # # #
 
 wikipedia_resource_files = $(shell $(GLIB_COMPILE_RESOURCES) --sourcedir=$(srcdir)/data --generate-dependencies $(srcdir)/data/eos-wikipedia-domain.gresource.xml)
diff --git a/configure.ac b/configure.ac
index a74e3e0..057f98e 100644
--- a/configure.ac
+++ b/configure.ac
@@ -115,6 +115,8 @@ AC_PATH_PROG([GIRDOCTOOL], [g-ir-doc-tool], [notfound])
 AC_ARG_VAR([GIRDOCTOOL], [Path to g-ir-doc-tool])
 AC_PATH_PROG([YELPBUILD], [yelp-build], [notfound])
 AC_ARG_VAR([YELPBUILD], [Path to yelp-build])
+AC_PATH_PROG([NATURALDOCS], [naturaldocs], [notfound])
+AC_ARG_VAR([NATURALDOCS], [Path to naturaldocs])
 GLIB_COMPILE_RESOURCES=`$PKG_CONFIG --variable glib_compile_resources gio-2.0`
 AC_SUBST(GLIB_COMPILE_RESOURCES)
 
@@ -175,12 +177,22 @@ AS_IF([test "x$enable_gir_doc" = "xyes"], [
 		[AC_MSG_ERROR([yelp-build must be installed for --enable-gir-doc])])])
 AM_CONDITIONAL([ENABLE_GIR_DOC], [test "x$enable_gir_doc" = "xyes"])
 
-# For 'make dist' or 'make distcheck', both --enable-gtk-doc and
-# --enable-gir-doc are required
+# --enable-js-doc: Build pure Javascript module documentation.
+AC_ARG_ENABLE([js-doc],
+	[AS_HELP_STRING([--enable-js-doc],
+		[Build documentation for pure Javascript modules @<:@default=no@:>@])])
+AS_IF([test "x$enable_js_doc" = "xyes"], [
+	AS_IF([test "x$NATURALDOCS" = "xnotfound"],
+		[AC_MSG_ERROR([NaturalDocs must be installed for --enable-js-doc])])])
+AM_CONDITIONAL([ENABLE_JS_DOC], [test "x$enable_js_doc" = "xyes"])
+
+# For 'make dist' or 'make distcheck', all three of --enable-gtk-doc,
+# --enable-gir-doc, and --enable-js-doc are required
 AC_MSG_CHECKING([whether this configuration allows building distributions])
 can_make_dist=yes
 AM_COND_IF([ENABLE_GTK_DOC], [], [can_make_dist=no])
 AM_COND_IF([ENABLE_GIR_DOC], [], [can_make_dist=no])
+AM_COND_IF([ENABLE_JS_DOC], [], [can_make_dist=no])
 AM_CONDITIONAL([CAN_MAKE_DIST], [test "x$can_make_dist" = "xyes"])
 AC_MSG_RESULT([$can_make_dist])
 
diff --git a/docs/reference/webhelper/Makefile.am.inc b/docs/reference/webhelper/Makefile.am.inc
new file mode 100644
index 0000000..0d99169
--- /dev/null
+++ b/docs/reference/webhelper/Makefile.am.inc
@@ -0,0 +1,44 @@
+if ENABLE_JS_DOC
+
+# This is for moving eos.css into the NaturalDocs project dir, which is in the
+# build tree rather than the source tree.
+docs/reference/webhelper/eos.css: docs/reference/webhelper/eos.css.in
+	$(AM_V_GEN)$(MKDIR_P) $(@D)
+	cp $< $@
+
+docs/reference/webhelper/html/index.html: webhelper/webhelper.js docs/reference/webhelper/eos.css
+	$(MKDIR_P) $(@D)
+	naturaldocs -i $(<D) -o HTML $(@D) -p $(@D)/.. -s Default eos -hl All
+
+all-local: docs/reference/webhelper/html/index.html
+
+webhelper_docs_files = \
+	docs/reference/webhelper/html/index.html \
+	docs/reference/webhelper/html/files/webhelper-js.html \
+	docs/reference/webhelper/html/index/Classes.html \
+	docs/reference/webhelper/html/index/Functions.html \
+	docs/reference/webhelper/html/index/General.html \
+	docs/reference/webhelper/html/index/Properties.html \
+	docs/reference/webhelper/html/javascript/main.js \
+	docs/reference/webhelper/html/javascript/prettify.js \
+	docs/reference/webhelper/html/javascript/searchdata.js \
+	docs/reference/webhelper/html/search/*.html \
+	docs/reference/webhelper/html/styles/*.css \
+	$(NULL)
+webhelper_extra_clean_files = \
+	docs/reference/webhelper/Data/*.nd \
+	docs/reference/webhelper/Menu.txt \
+	docs/reference/webhelper/Topics.txt \
+	docs/reference/webhelper/Languages.txt \
+	docs/reference/webhelper/eos.css \
+	$(NULL)
+EXTRA_DIST += \
+	$(webhelper_docs_files) \
+	docs/reference/webhelper/eos.css.in \
+	$(NULL)
+CLEANFILES += \
+	$(webhelper_docs_files) \
+	$(webhelper_extra_clean_files) \
+	$(NULL)
+
+endif
diff --git a/docs/reference/webhelper/eos.css.in b/docs/reference/webhelper/eos.css.in
new file mode 100644
index 0000000..7307859
--- /dev/null
+++ b/docs/reference/webhelper/eos.css.in
@@ -0,0 +1,46 @@
+* {
+    font-family: "Source Sans Pro";
+}
+
+p {
+    font-size: 16pt;
+    text-indent: 0;
+    margin-bottom: 1em;
+}
+
+.STitle,
+.CTitle,
+.CGroup .CTitle {
+    font-size: 18pt;
+}
+
+.CHeading {
+    font-size: 14pt;
+}
+
+.SMain td,
+.SClass td,
+.STable,
+.CDLEntry,
+.CDLDescription {
+    font-size: 12pt;
+}
+
+.ContentPage #Content,
+.IndexPage #Index {
+    margin-left: 55ex;
+}
+
+.ContentPage #Menu,
+.IndexPage #Menu {
+    font-size: 12pt;
+    width: 41ex;
+}
+
+.Prototype *,
+.prettyprint *,
+.CBody pre,
+.CDLEntry {
+    font-family: "DejaVu Sans Mono";
+    font-size: 13pt;
+}
\ No newline at end of file
diff --git a/webhelper/webhelper.js b/webhelper/webhelper.js
index ccce9e7..1992973 100644
--- a/webhelper/webhelper.js
+++ b/webhelper/webhelper.js
@@ -5,21 +5,71 @@ const WebKit = imports.gi.WebKit;
 
 const EOS_URI_SCHEME = 'endless://';
 
-
+/**
+ * Namespace: WebHelper
+ * Convenience library for running web applications
+ *
+ * WebHelper is a convenience library for displaying web applications inside a
+ * GTK container running WebKitGTK (currently WebKit 1, not 2.)
+ * Although WebKit provides an easy way of communicating from GTK code to
+ * the in-browser Javascript, through the execute_script() method, it is not so
+ * easy to communicate the other way around.
+ *
+ * WebHelper solves that problem by detecting when the web page navigates to a
+ * custom action URI.
+ * The custom URI corresponds to a function that you define in
+ * <Application._webActions>, and you can pass parameters to the
+ * function.
+ *
+ * Another often-encountered problem is localizing text through the same API as
+ * your main GTK program.
+ * WebHelper solves this problem by allowing you to mark strings in your HTML
+ * page and translating them through a function of your choice when you run
+ * <Application.translate_html()>.
+ */
+
+/**
+ * Class: Application
+ * Main application class for a WebHelper application
+ *
+ * The application class in GJS for your web application should extend
+ * WebHelper.Application.
+ *
+ * You should set up any WebViews that you create, by connecting
+ * <web_actions_handler()>, so that they can handle custom action URIs.
+ */
 const Application = new Lang.Class({
     Name: 'WebApplication',
     Extends: Endless.Application,
 
-//  Set of actions that may be invoked from a WebView.
-//  Declare them as function(dict), and use links with the format
-//  "endless://actionName?parameter=value"
-
+    /**
+     * Property: _webActions
+     * Set of actions that may be invoked from a WebView
+     *
+     * Declare them as a function that takes a dict as a parameter, and use
+     * links with the format "endless://actionName?parameter=value"
+     *
+     * *Note* This API will likely disappear and be replaced by a method
+     * add_web_action().
+     * That is the reason for the underscore starting the name.
+     */
     _webActions: { },
 
-    // This callback does the translation from URI to action
-    // webview.connect('navigation-policy-decision-requested',
-    //     Lang.bind(this, this.web_actions_handler));
-
+    /**
+     * Callback: web_actions_handler
+     * Navigation callback which routes the custom URIs to actions
+     *
+     * When you create a web view in which you want to run a web application
+     * that uses custom action URIs, remember to set it up by connecting this
+     * callback to its "navigation-policy-decision-requested" signal. The
+     * following code will do this:
+     *
+     * > webview.connect('navigation-policy-decision-requested',
+     * >     Lang.bind(app, app.web_actions_handler));
+     *
+     * where 'webview' is the web view, and 'app' is the WebHelper.Application
+     * instance.
+     */
     web_actions_handler: function(webview, frame, request, action, policy_decision) {
         let uri = request.get_uri();
 
@@ -68,6 +118,52 @@ const Application = new Lang.Class({
         return dom.get_element_by_id(id);
     },
 
+    /**
+     * Property: _translationFunction
+     * Function which transforms all translatable text
+     *
+     * When you plan to use the <translate_html()> function to translate text in
+     * your web application, set this property to the translation function.
+     * The function must take one parameter, a string, and also return a
+     * string -- for example, gettext().
+     *
+     * *Note* This API will likely disappear and be replaced by a read-write
+     * translation_function property.
+     * That is the reason for the underscore starting the name.
+     */
+
+    /**
+     * Method: translate_html
+     * Translate all translatable text currently showing in a web view
+     *
+     * Parameters:
+     *   webview - the WebView containing the text to translate.
+     *
+     * Another problem with running web applications inside a GTK container is
+     * keeping all the localization data in the same place.
+     * For example, the most obvious way to do localization in a GTK application
+     * is to use gettext(), but that does not work so easily inside a web view.
+     *
+     * In a <WebHelper.Application>, you can mark strings in your HTML for
+     * translation by enclosing them in
+     * > <span name="translatable">String to be translated</span>
+     * or just putting the "translatable" name directly on the element
+     * containing the string, e.g. <p> or <h1>.
+     *
+     * Then after the web view has finished loading, call <translate_html()> on
+     * it, and each of the marked strings will be passed to the function that
+     * you specify using the <_translationFunction> property.
+     * The return value from <_translationFunction> will be substituted into the
+     * HTML instead of the original string.
+     *
+     * Example:
+     * > app._translationFunction = _;
+     * > webview.connect('notify::load-status',
+     * >     Lang.bind(app, function(webview) {
+     * >         if(webview.load_status == WebKit.LoadStatus.FINISHED)
+     * >             this.translate_html(webview);
+     * >     }));
+     */
     translate_html: function(webview) {
         let dom = webview.get_dom_document();