summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPhilip Chimento <philip@endlessm.com>2013-09-17 16:47:30 -0700
committerPhilip Chimento <philip@endlessm.com>2013-09-19 14:24:11 -0700
commit4549971954b8b67ed714048730060c9f66f4f56f (patch)
tree8643ba92fb425b0011c4468dbf76915eac989c83
parentbf158e4986b6bf5570de2f6bd9de9e4be9b96608 (diff)
Documentation for WebHelper
This adds the infrastructure for autogenerating HTML documentation from a Javascript module using NaturalDocs, and then adds documentation comments to webhelper.js. [endlessm/eos-sdk#302]
-rw-r--r--.gitignore8
-rw-r--r--Makefile.am10
-rw-r--r--configure.ac16
-rw-r--r--docs/reference/webhelper/Makefile.am.inc44
-rw-r--r--docs/reference/webhelper/eos.css.in46
-rw-r--r--webhelper/webhelper.js114
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();