Bug 17045 - [GTK] Documentation
: [GTK] Documentation
Status: RESOLVED FIXED
: WebKit
WebKit Gtk
: 528+ (Nightly build)
: PC All
: P2 Normal
Assigned To:
:
: Gtk
:
:
  Show dependency treegraph
 
Reported: 2008-01-28 09:43 PST by
Modified: 2009-03-30 20:22 PST (History)


Attachments
gtk-doc makefile (1.23 KB, text/plain)
2008-01-28 09:46 PST, Luca Bruno
no flags Details
Add gtk-doc build infrastructure. (6.86 KB, patch)
2008-03-12 10:29 PST, Tommi Komulainen
zecke: review-
Review Patch | Details | Formatted Diff | Diff
Fix existing API Documentation (14.39 KB, patch)
2008-11-22 21:41 PST, Holger Freyther
no flags Review Patch | Details | Formatted Diff | Diff
Add gtk-doc configuration files (10.20 KB, patch)
2008-11-22 21:43 PST, Holger Freyther
no flags Review Patch | Details | Formatted Diff | Diff
Fix existing API Documentation (18.18 KB, patch)
2008-11-22 21:45 PST, Holger Freyther
no flags Review Patch | Details | Formatted Diff | Diff
Add gtk-doc configuration files (10.20 KB, patch)
2008-11-22 21:46 PST, Holger Freyther
no flags Review Patch | Details | Formatted Diff | Diff
Integrate gtk-doc in the build process (7.34 KB, patch)
2008-11-22 21:49 PST, Holger Freyther
no flags Review Patch | Details | Formatted Diff | Diff
WIP Add section information and examples (4.33 KB, patch)
2008-11-22 21:51 PST, Holger Freyther
no flags Review Patch | Details | Formatted Diff | Diff
Add Section Documentation and informal examples (17.75 KB, patch)
2008-11-29 11:48 PST, Holger Freyther
no flags Review Patch | Details | Formatted Diff | Diff
doc structure updates required after the initial patch is landed, or should we merge? (4.24 KB, patch)
2009-03-02 06:20 PST, Gustavo Noronha (kov)
zecke: review+
Review Patch | Details | Formatted Diff | Diff
section docs for two new objects (1.51 KB, patch)
2009-03-02 06:21 PST, Gustavo Noronha (kov)
no flags Review Patch | Details | Formatted Diff | Diff
changes I made to support 1.1.2 (5.94 KB, patch)
2009-03-15 11:23 PST, Gustavo Noronha (kov)
zecke: review+
Review Patch | Details | Formatted Diff | Diff
Updated gtk-doc configuration files for 1.1.4 (2.51 KB, patch)
2009-03-30 13:15 PST, Gustavo Noronha (kov)
zecke: review+
Review Patch | Details | Formatted Diff | Diff
Wrote a section about using the WEBKIT_DEBUG environment variable. (3.60 KB, patch)
2009-03-30 13:15 PST, Gustavo Noronha (kov)
no flags Review Patch | Details | Formatted Diff | Diff
integrate gtk-doc in the build process (9.43 KB, patch)
2009-03-30 19:26 PST, Gustavo Noronha (kov)
no flags Review Patch | Details | Formatted Diff | Diff


Note

You need to log in before you can comment on or make changes to this bug.


Description From 2008-01-28 09:43:41 PST
Hello,
GTK+ port is currently missing the gtk-doc generated documentation.
------- Comment #1 From 2008-01-28 09:46:16 PST -------
Created an attachment (id=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.
------- Comment #2 From 2008-03-12 10:29:03 PST -------
Created an attachment (id=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.
------- Comment #3 From 2008-03-12 11:15:54 PST -------
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.
------- Comment #4 From 2008-03-21 15:40:54 PST -------
(From update of attachment 19701 [details])
The patch is very good, but it is not working for srcdir != builddir. The documentation gets generated in the srcdir.
------- Comment #5 From 2008-10-26 08:06:57 PST -------
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
------- Comment #6 From 2008-11-22 21:31:28 PST -------
(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. :)
------- Comment #7 From 2008-11-22 21:41:36 PST -------
Created an attachment (id=25386) [details]
Fix existing API Documentation

Fix the existing API Documentation. Fix references, naming of variables.
------- Comment #8 From 2008-11-22 21:43:26 PST -------
Created an attachment (id=25387) [details]
Add gtk-doc configuration files

Add the required files for gtk-doc. This includes -docs.sgml, -sections.txt.
------- Comment #9 From 2008-11-22 21:45:13 PST -------
Created an attachment (id=25388) [details]
Fix existing API Documentation

Fix existing API documentation. Naming of parameters, signal references.
------- Comment #10 From 2008-11-22 21:46:17 PST -------
Created an attachment (id=25389) [details]
Add gtk-doc configuration files

The correct patch. -docs.sgml, -sections.txt
------- Comment #11 From 2008-11-22 21:49:54 PST -------
Created an attachment (id=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.
------- Comment #12 From 2008-11-22 21:51:30 PST -------
Created an attachment (id=25391) [details]
WIP Add section information and examples

Work In Progress. Add SECTION: and programlisting/examples to the documentation.
------- Comment #13 From 2008-11-23 12:32:01 PST -------
(From update of attachment 25389 [details])
rs=me
------- Comment #14 From 2008-11-23 14:30:06 PST -------
(From update of attachment 25388 [details])
Clearing review.
------- Comment #15 From 2008-11-23 14:32:58 PST -------
(From update of attachment 25389 [details])
Clearing review too.
------- Comment #16 From 2008-11-25 04:46:53 PST -------
(From update of attachment 25390 [details])
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,
------- Comment #17 From 2008-11-29 11:48:16 PST -------
Created an attachment (id=25597) [details]
Add Section Documentation and informal examples

Add SECTION for our classes/objects, add some informal examples.
------- Comment #18 From 2008-12-08 07:09:56 PST -------
(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
------- Comment #19 From 2008-12-20 17:55:59 PST -------
(From update of attachment 25597 [details])
Looks fine, r=me.
------- Comment #20 From 2008-12-31 09:59:46 PST -------
(From update of attachment 25597 [details])
Landed in r39532 and clearing review.
------- Comment #21 From 2009-03-02 06:20:23 PST -------
Created an attachment (id=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.
------- Comment #22 From 2009-03-02 06:21:11 PST -------
Created an attachment (id=28170) [details]
section docs for two new objects
------- Comment #23 From 2009-03-15 11:10:33 PST -------
(In reply to comment #22)
> Created an attachment (id=28170) [details] [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.
------- Comment #24 From 2009-03-15 11:23:44 PST -------
Created an attachment (id=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.
------- Comment #25 From 2009-03-30 13:15:44 PST -------
Created an attachment (id=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(-)
------- Comment #26 From 2009-03-30 13:15:50 PST -------
Created an attachment (id=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(-)
------- Comment #27 From 2009-03-30 19:20:51 PST -------
(In reply to comment #21)
> Created an attachment (id=28169) [details] [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.
------- Comment #28 From 2009-03-30 19:23:40 PST -------
(From update of attachment 29083 [details])

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

Isn't this --enable-debug?
------- Comment #29 From 2009-03-30 19:26:10 PST -------
Created an attachment (id=29106) [details]
integrate gtk-doc in the build process
------- Comment #30 From 2009-03-30 19:27:38 PST -------
(From update of attachment 28640 [details])


> +    <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. :)
------- Comment #31 From 2009-03-30 19:33:16 PST -------
(From update of attachment 29106 [details])

> +    <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.
------- Comment #32 From 2009-03-30 19:51:53 PST -------
(From update of attachment 29106 [details])
Landed as r42123. Clearing the review flag.
------- Comment #33 From 2009-03-30 19:57:09 PST -------
(From update of attachment 28640 [details])
Okay, I got updated, WebKitSoupAuthDialog is supposed to be public API... Which means it deserves some padding in the class struct. :)
------- Comment #34 From 2009-03-30 20:17:59 PST -------
(From update of attachment 29083 [details])
Landed as r42124, merged with attachment 28170 [details] and a piece of 28640, for better organization.
------- Comment #35 From 2009-03-30 20:18:12 PST -------
(From update of attachment 28170 [details])
Landed as r42124, merged with attachment 29083 [details] and a piece of 28640, for better organization.
------- Comment #36 From 2009-03-30 20:22:28 PST -------
Landed as r42123, r42124, and r42125.