Bug 17045 - [GTK] Documentation
Summary: [GTK] Documentation
Status: RESOLVED FIXED
Alias: None
Product: WebKit
Classification: Unclassified
Component: WebKitGTK (show other bugs)
Version: 528+ (Nightly build)
Hardware: PC All
: P2 Normal
Assignee: Nobody
URL:
Keywords: Gtk
Depends on:
Blocks:
 
Reported: 2008-01-28 09:43 PST by Luca Bruno
Modified: 2009-03-30 20:22 PDT (History)
6 users (show)

See Also:


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 PDT, Tommi Komulainen
zecke: review-
Details | Formatted Diff | Diff
Fix existing API Documentation (14.39 KB, patch)
2008-11-22 21:41 PST, Holger Freyther
no flags Details | Formatted Diff | Diff
Add gtk-doc configuration files (10.20 KB, patch)
2008-11-22 21:43 PST, Holger Freyther
no flags Details | Formatted Diff | Diff
Fix existing API Documentation (18.18 KB, patch)
2008-11-22 21:45 PST, Holger Freyther
no flags Details | Formatted Diff | Diff
Add gtk-doc configuration files (10.20 KB, patch)
2008-11-22 21:46 PST, Holger Freyther
no flags 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 Details | Formatted Diff | Diff
WIP Add section information and examples (4.33 KB, patch)
2008-11-22 21:51 PST, Holger Freyther
no flags Details | Formatted Diff | Diff
Add Section Documentation and informal examples (17.75 KB, patch)
2008-11-29 11:48 PST, Holger Freyther
no flags 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+
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 Details | Formatted Diff | Diff
changes I made to support 1.1.2 (5.94 KB, patch)
2009-03-15 11:23 PDT, Gustavo Noronha (kov)
zecke: review+
Details | Formatted Diff | Diff
Updated gtk-doc configuration files for 1.1.4 (2.51 KB, patch)
2009-03-30 13:15 PDT, Gustavo Noronha (kov)
zecke: review+
Details | Formatted Diff | Diff
Wrote a section about using the WEBKIT_DEBUG environment variable. (3.60 KB, patch)
2009-03-30 13:15 PDT, Gustavo Noronha (kov)
no flags Details | Formatted Diff | Diff
integrate gtk-doc in the build process (9.43 KB, patch)
2009-03-30 19:26 PDT, Gustavo Noronha (kov)
no flags Details | Formatted Diff | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Luca Bruno 2008-01-28 09:43:41 PST
Hello,
GTK+ port is currently missing the gtk-doc generated documentation.
Comment 1 Luca Bruno 2008-01-28 09:46:16 PST
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.
Comment 2 Tommi Komulainen 2008-03-12 10:29:03 PDT
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.
Comment 3 Tommi Komulainen 2008-03-12 11:15:54 PDT
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 Holger Freyther 2008-03-21 15:40:54 PDT
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.
Comment 5 Murray Cumming 2008-10-26 08:06:57 PDT
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 Holger Freyther 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 Holger Freyther 2008-11-22 21:41:36 PST
Created attachment 25386 [details]
Fix existing API Documentation

Fix the existing API Documentation. Fix references, naming of variables.
Comment 8 Holger Freyther 2008-11-22 21:43:26 PST
Created attachment 25387 [details]
Add gtk-doc configuration files

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

Fix existing API documentation. Naming of parameters, signal references.
Comment 10 Holger Freyther 2008-11-22 21:46:17 PST
Created attachment 25389 [details]
Add gtk-doc configuration files

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

Work In Progress. Add SECTION: and programlisting/examples to the documentation.
Comment 13 Sam Weinig 2008-11-23 12:32:01 PST
Comment on attachment 25389 [details]
Add gtk-doc configuration files

rs=me
Comment 14 Holger Freyther 2008-11-23 14:30:06 PST
Comment on attachment 25388 [details]
Fix existing API Documentation

Clearing review.
Comment 15 Holger Freyther 2008-11-23 14:32:58 PST
Comment on attachment 25389 [details]
Add gtk-doc configuration files

Clearing review too.
Comment 16 Jan Alonzo 2008-11-25 04:46:53 PST
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,
Comment 17 Holger Freyther 2008-11-29 11:48:16 PST
Created attachment 25597 [details]
Add Section Documentation and informal examples

Add SECTION for our classes/objects, add some informal examples.
Comment 18 Luca Ferretti 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 Nikolas Zimmermann 2008-12-20 17:55:59 PST
Comment on attachment 25597 [details]
Add Section Documentation and informal examples

Looks fine, r=me.
Comment 20 Holger Freyther 2008-12-31 09:59:46 PST
Comment on attachment 25597 [details]
Add Section Documentation and informal examples

Landed in r39532 and clearing review.
Comment 21 Gustavo Noronha (kov) 2009-03-02 06:20:23 PST
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.
Comment 22 Gustavo Noronha (kov) 2009-03-02 06:21:11 PST
Created attachment 28170 [details]
section docs for two new objects
Comment 23 Christian Dywan 2009-03-15 11:10:33 PDT
(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.
Comment 24 Gustavo Noronha (kov) 2009-03-15 11:23:44 PDT
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.
Comment 25 Gustavo Noronha (kov) 2009-03-30 13:15:44 PDT
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(-)
Comment 26 Gustavo Noronha (kov) 2009-03-30 13:15:50 PDT
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(-)
Comment 27 Holger Freyther 2009-03-30 19:20:51 PDT
(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.
Comment 28 Holger Freyther 2009-03-30 19:23:40 PDT
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?
Comment 29 Gustavo Noronha (kov) 2009-03-30 19:26:10 PDT
Created attachment 29106 [details]
integrate gtk-doc in the build process
Comment 30 Holger Freyther 2009-03-30 19:27:38 PDT
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. :)
Comment 31 Holger Freyther 2009-03-30 19:33:16 PDT
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.
Comment 32 Gustavo Noronha (kov) 2009-03-30 19:51:53 PDT
Comment on attachment 29106 [details]
integrate gtk-doc in the build process

Landed as r42123. Clearing the review flag.
Comment 33 Holger Freyther 2009-03-30 19:57:09 PDT
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. :)
Comment 34 Gustavo Noronha (kov) 2009-03-30 20:17:59 PDT
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.
Comment 35 Gustavo Noronha (kov) 2009-03-30 20:18:12 PDT
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.
Comment 36 Gustavo Noronha (kov) 2009-03-30 20:22:28 PDT
Landed as r42123, r42124, and r42125.