Bug 17045 – [GTK] Documentation

• Component: WebKitGTK
• Status: RESOLVED FIXED

[Luca Bruno]

Hello,
GTK+ port is currently missing the gtk-doc generated documentation.

[Luca Bruno]

Created attachment 18737 [details]
gtk-doc makefile

This is a very tweaked GNUmakefile for generating docs with gtk-doc. What you have to do is to put the GNUmakefile inside WebKit/gtk/docs then type make from inside the docs directory.

[Tommi Komulainen]

Created attachment 19701 [details]
Add gtk-doc build infrastructure.

Here's an alternate implementation for setting up the infrastructure, following more closely how gtk-doc is intended to be used (gtkdocize, Makefile.am including gtk-doc.make)

With --ignore-decorators="WEBKIT_API" and IGNORE_HFILES one can filter out / avoid most issues, I'm sure the same could be done even without autotools integration.

Whether or not you use autotools I'd argue you should maintain the webkit-docs.sgml file yourself in order to set up any kind of reasonable structure.

[Tommi Komulainen]

On related note, to add overview documentation for the whole class you should add a template similar to the following in each relevant .cpp file:

+/**
+ * SECTION:webkitwebview
+ * @short_description: Widget that displays a WebkitWebFrame
+ * @include: webkit/webkit.h
+ *
+ * Not written yet (OOPS!)
+ */


It's unclear for me how exactly the SECTION id is derived, I suppose it's the basename of the file.

[Holger Freyther]

Comment on attachment 19701 [details]
Add gtk-doc build infrastructure.

The patch is very good, but it is not working for srcdir != builddir. The documentation gets generated in the srcdir.

[Murray Cumming]

When you have gtk-doc working, please request that it be added to library.gnome.org (via the website product in bugzilla.gnome.org) and add a link to it from http://live.gnome.org/WebKitGtk

[Holger Freyther]

(In reply to comment #4)
> (From update of attachment 19701 [details] [review])
> The patch is very good, but it is not working for srcdir != builddir. The
> documentation gets generated in the srcdir.

hehe, month passed and I recognize that srcdir != builddir is not possible with gtk-doc anyway? Why did no one point that out. :)

[Holger Freyther]

Created attachment 25386 [details]
Fix existing API Documentation

Fix the existing API Documentation. Fix references, naming of variables.

[Holger Freyther]

Created attachment 25387 [details]
Add gtk-doc configuration files

Add the required files for gtk-doc. This includes -docs.sgml, -sections.txt.

[Holger Freyther]

Created attachment 25388 [details]
Fix existing API Documentation

Fix existing API documentation. Naming of parameters, signal references.

[Holger Freyther]

Created attachment 25389 [details]
Add gtk-doc configuration files

The correct patch. -docs.sgml, -sections.txt

[Holger Freyther]

Created attachment 25390 [details]
Integrate gtk-doc in the build process

This looks awfully similar to the original patch. To build the documentation we require srcdir == builddir. This is true for any user of gtk-doc (pango and ...), we also need a recursive target as gtk-doc.make will not play nicely with our GNUmakefile.am.

The good thing is that generating documentation is not enabled by default so we will not break anyones build. To generate the documentation --enable-gtk-doc needs to be passed.

[Holger Freyther]

Created attachment 25391 [details]
WIP Add section information and examples

Work In Progress. Add SECTION: and programlisting/examples to the documentation.

[Sam Weinig]

Comment on attachment 25389 [details]
Add gtk-doc configuration files

rs=me

[Holger Freyther]

Comment on attachment 25388 [details]
Fix existing API Documentation

Clearing review.

[Holger Freyther]

Comment on attachment 25389 [details]
Add gtk-doc configuration files

Clearing review too.

[Jan Alonzo]

Comment on attachment 25390 [details]
Integrate gtk-doc in the build process

Hi Holger

> +INCLUDES= \
> +	-I$(top_srcdir)/WebKit/gtk \
> +	-I$(top_builddir)/WebKit/gtk \
> +	$(global_cppflags) \
> +	$(global_cflags) \
> +	-I$(top_srcdir) \
> +	-I$(top_srcdir)/JavaScriptCore \
> +	-I$(top_srcdir)/JavaScriptCore/ForwardingHeaders \
> +	-I$(top_srcdir)/JavaScriptCore/parser \
> +	-I$(top_srcdir)/JavaScriptCore/wtf \
> +	-I$(top_builddir)/DerivedSources \
> +	$(GLOBALDEPS_CFLAGS) \
> +	$(CAIRO_CFLAGS) \
> +	$(GTK_CFLAGS)

Do we need all of the above?

> diff --git a/WebKit/gtk/docs/version.xml.in b/WebKit/gtk/docs/version.xml.in
> new file mode 100644
> index 0000000..d78bda9
> --- /dev/null
> +++ b/WebKit/gtk/docs/version.xml.in
> @@ -0,0 +1 @@
> +@VERSION@

Should we add version.xml.in to EXTRA_DIST?

> diff --git a/WebKit/gtk/docs/webkitgtk-docs.sgml b/WebKit/gtk/docs/webkitgtk-docs.sgml
> index 9b41ed6..2f50ce5 100644
> --- a/WebKit/gtk/docs/webkitgtk-docs.sgml
> +++ b/WebKit/gtk/docs/webkitgtk-docs.sgml
> @@ -1,14 +1,12 @@
>  <?xml version="1.0"?>
>  <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
> -               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
> +               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
> +<!ENTITY version SYSTEM "version.xml">
> +]>
>  <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
>    <bookinfo>
> -    <title>webkitgtk Reference Manual</title>
> -    <releaseinfo>
> -      for webkitgtk [VERSION]
> -      The latest version of this documentation can be found on-line at
> -      <ulink role="online-location" url="http://[SERVER]/webkitgtk/index.html">http://[SERVER]/webkitgtk/</ulink>.
> -    </releaseinfo>
> +    <title>WebKit/Gtk+ Reference Manual</title>
> +    <releaseinfo>for WebKit/Gtk+ &version;</releaseinfo>
>    </bookinfo>
>  
>    <chapter>
> diff --git a/autogen.sh b/autogen.sh
> index a929538..882eba9 100755
> --- a/autogen.sh
> +++ b/autogen.sh
> @@ -10,6 +10,14 @@ cd $srcdir
>  
>  DIE=0
>  
> +(gtkdocize --version) < /dev/null > /dev/null 2>&1 || {
> +    echo
> +    echo "You must have gtkdocize installed to compile $PROJECT."
> +    echo "Install the appropriate package for your distribution,"
> +    echo "or get the source tarball at http://ftp.gnome.org/pub/GNOME/sources/gtk-doc/"
> +    DIE=1
> +}
> +
>  (autoconf --version) < /dev/null > /dev/null 2>&1 || {
>      echo
>      echo "You must have autoconf installed to compile $PROJECT."
> @@ -46,6 +54,7 @@ rm -rf $top_srcdir/autom4te.cache
>  
>  touch README INSTALL
>  
> +gtkdocize || exit $?

You might want to move this after LIBTOOLIZE below.

>  aclocal || exit $?
>  $LIBTOOLIZE --force || exit $?
>  autoheader || exit $?
> diff --git a/configure.ac b/configure.ac
> index f48f98f..c37d3ef 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -670,6 +670,8 @@ if test "$enable_video" = "yes"; then
>      html_flags=yes
>  fi
>  
> +GTK_DOC_CHECK([1.10])

Please move this at the top so we fail early if gtk-doc is not found but builder wants gtk-doc.

> +
>  # OS conditionals
>  AM_CONDITIONAL([OS_WIN32],[test "$os_win32" = "yes"])
>  AM_CONDITIONAL([OS_UNIX],[test "$os_win32" = "no"])
> @@ -718,6 +720,8 @@ AC_CONFIG_FILES([
>  GNUmakefile
>  WebKit/gtk/webkit-1.0.pc:WebKit/gtk/webkit.pc.in
>  WebKit/gtk/webkit/webkitversion.h
> +WebKit/gtk/docs/GNUmakefile
> +WebKit/gtk/docs/version.xml

Lastly, try to do the same as the pc file generation above (e.g. ...version.xml:WebKit/gtk/docs/versio.xml.in)

Cheers,

[Holger Freyther]

Created attachment 25597 [details]
Add Section Documentation and informal examples

Add SECTION for our classes/objects, add some informal examples.

[Luca Ferretti]

(In reply to comment #15)

> index f48f98f..c37d3ef 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -670,6 +670,8 @@ if test "$enable_video" = "yes"; then
>      html_flags=yes
>  fi
>  
> +GTK_DOC_CHECK([1.10])
> +

gtk-doc help suggest to add AC_CONFIG_MACRO_DIR(m4) too (see http://library.gnome.org/devel/gtk-doc-manual/stable/settingup_autoconf.html)

> diff --git a/WebKit/gtk/docs/GNUmakefile.am b/WebKit/gtk/docs/GNUmakefile.am
> new file mode 100644

I think you could remove general comment about macro usage, keeping only relevant info. Could also be useful add
  DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc
As suggested http://library.gnome.org/devel/gtk-doc-manual/stable/settingup_automake.html

About documentation itself, could be useful add an Overview section like:

 <chapter id="overview">
    <title>WebKit/Gtk Overview</title>
    <para>
      WebKit/Gtk is the <ulink role="online-location" url="http://www.gtk.org">GTK+</ulink>
      port for <ulink role="online-location" url="http://www.webkit.org">WebKit</ulink>,
      the open source web browser engine. A port of WebKit is a unique 
      combination of platform technologies that run the WebKit engine.
      WebKit/Gtk port uses the graphic tecnologies provided by GTK+ toolkit.
    </para>
  </chapter>

this overview chapter could be extended with sub-sections related to building (dependencies, configure options..), compiling (against webkit, i.e. what pkg-config stuff you have to use in order to use webkitgtk in your project) and other stuff like the glib and gtk api refs overview (see [1] and [2])

Stupid final note: don't forget to add version control "ignore" property to files generated by gtk-doc, for example gtk-doc.make and all .html files.

[1] http://library.gnome.org/devel/glib/stable/glib.html
[2] http://library.gnome.org/devel/gtk/stable/gtk.html

[Nikolas Zimmermann]

Comment on attachment 25597 [details]
Add Section Documentation and informal examples

Looks fine, r=me.

[Holger Freyther]

Comment on attachment 25597 [details]
Add Section Documentation and informal examples

Landed in r39532 and clearing review.

[Gustavo Noronha (kov)]

Created attachment 28169 [details]
doc structure updates required after the initial patch is landed, or should we merge?

I'm not providing a changelog here, but I will of course add one when we land. I'm posting the patches here just so that they don't get forgotten in my local computer.

[Gustavo Noronha (kov)]

Created attachment 28170 [details]
section docs for two new objects

[Christian Dywan]

(In reply to comment #22)
> Created an attachment (id=28170) [review]
> section docs for two new objects

I think the adjective "asynchronous(ly)" should be mentioned in the section about the WebPolicyAction since that's the main reason why it exists.

[Gustavo Noronha (kov)]

Created attachment 28640 [details]
changes I made to support 1.1.2

This is a fair amount of unrelated changes. I intend to split them when we have landed the initial bits, so that they make sense as changesets.

[Gustavo Noronha (kov)]

Created attachment 29082 [details]
Updated gtk-doc configuration files for 1.1.4

 WebKit/gtk/docs/webkitgtk-docs.sgml    |    6 ++++++
 WebKit/gtk/docs/webkitgtk-sections.txt |    9 +++++++++
 2 files changed, 15 insertions(+), 0 deletions(-)

[Gustavo Noronha (kov)]

Created attachment 29083 [details]
Wrote a section about using the WEBKIT_DEBUG environment variable.

 WebKit/gtk/docs/GNUmakefile.am        |    2 +-
 WebKit/gtk/docs/webkitenvironment.xml |   97 +++++++++++++++++++++++++++++++++
 WebKit/gtk/docs/webkitgtk-docs.sgml   |    5 ++
 3 files changed, 103 insertions(+), 1 deletions(-)

[Holger Freyther]

(In reply to comment #21)
> Created an attachment (id=28169) [review]
> doc structure updates required after the initial patch is landed, or should we
> merge?
> 
> I'm not providing a changelog here, but I will of course add one when we land.
> I'm posting the patches here just so that they don't get forgotten in my local
> computer.

please merge it, I can review the merged result then.

[Holger Freyther]

Comment on attachment 29083 [details]
Wrote a section about using the WEBKIT_DEBUG environment variable.


> +<literal>--debug</literal> to the <literal>configure</literal> script.

Isn't this --enable-debug?

[Gustavo Noronha (kov)]

Created attachment 29106 [details]
integrate gtk-doc in the build process

[Holger Freyther]

Comment on attachment 28640 [details]
changes I made to support 1.1.2



> +    <xi:include href="xml/webkitsoupauthdialog.xml"/>

Okay, we are not consistent here. Is WebKitSoupAuthDialog public API or not? I was under the assumption it is not.


> -    <title>Index of deprectaed symbols</title>
> +    <title>Index of deprecated symbols</title>

make that a separate spelling fix commit. :)

[Holger Freyther]

Comment on attachment 29106 [details]
integrate gtk-doc in the build process


> +    <title>WebKit/Gtk+ Reference Manual</title>
> +    <releaseinfo>for WebKit/Gtk+ &version;</releaseinfo>

Use the right name and we need to get some help from Jan to integrate it in the make all target.

[Gustavo Noronha (kov)]

Comment on attachment 29106 [details]
integrate gtk-doc in the build process

Landed as r42123. Clearing the review flag.

[Holger Freyther]

Comment on attachment 28640 [details]
changes I made to support 1.1.2

Okay, I got updated, WebKitSoupAuthDialog is supposed to be public API... Which means it deserves some padding in the class struct. :)

[Gustavo Noronha (kov)]

Comment on attachment 29083 [details]
Wrote a section about using the WEBKIT_DEBUG environment variable.

Landed as r42124, merged with attachment 28170 [details] and a piece of 28640, for better organization.

[Gustavo Noronha (kov)]

Comment on attachment 28170 [details]
section docs for two new objects

Landed as r42124, merged with attachment 29083 [details] and a piece of 28640, for better organization.

[Gustavo Noronha (kov)]

Landed as r42123, r42124, and r42125.