You Got A Question? Ask    GNOME Community!


How to Generate Native Gjs Docs

Well, two posts in the row about Gnome JavaScript. Yeap, I decided to do some Gnome GJS programming, for a change, cause lately I only do -omg how boring- databases or playing HoN – that’s not boring at all!

When I first started with Gjs (just basic things), I had this issue of translating C functions from C API to JavaScript (it feels a bit easier now!). Apparently there aren’t any native docs for JavaScript and you should check on C docs. To be honest is the first time time I see this on a language.

Today I asked Giovanni Campagna if there is any tool that auto-creates docs, and he pointed me out g-ir-doc-tool. He also told me that it doesn’t work very good, as it lacks docs for all the overrides and GJS specific stuff.

So I imagine that GJS Docs will come, when g-ir-doc-tool could export “correct” documentation. However we can create docs for our own use and I am doing this post with the hope that it would be proven useful  :)


Using g-ir-doc-tool

My system is a Fedora 20 with GNOME 3.10 and I will generate documentation just for Clutter, but obviously you can create docs for any library.

g-ir-doc-tool help:

$ g-ir-doc-tool --help
Usage: g-ir-doc-tool [options] GIR-file

Options:
  -h, --help            show this help message and exit
  -o OUTPUT, --output=OUTPUT
                        Directory to write output to
  -l LANGUAGE, --language=LANGUAGE
                        Output language
  --add-include-path=INCLUDE_PATHS
                        include paths for other GIR files
  --write-sections-file
                        Generate and write out a sections file

The Gir Files are under /usr/share/gir-1.0/

$ ls /usr/share/gir-1.0/
Atk-1.0.gir            GdkX11-2.0.gir          libxml2-2.0.gir
Atspi-2.0.gir          GdkX11-3.0.gir          Notify-0.7.gir
cairo-1.0.gir          GeocodeGlib-1.0.gir     Pango-1.0.gir
Cally-1.0.gir          Gio-2.0.gir             PangoCairo-1.0.gir
Clutter-1.0.gir        GIRepository-2.0.gir    PangoFT2-1.0.gir
ClutterGdk-1.0.gir     GL-1.0.gir              PangoXft-1.0.gir
ClutterX11-1.0.gir     GLib-2.0.gir            Polkit-1.0.gir
Cogl-1.0.gir           GMime-2.6.gir           PolkitAgent-1.0.gir
CoglPango-1.0.gir      GModule-2.0.gir         Poppler-0.18.gir
DBus-1.0.gir           GnomeDesktop-3.0.gir    Secret-1.gir
DBusGLib-1.0.gir       GnomeKeyring-1.0.gir    SecretUnstable-0.gir
EBook-1.2.gir          Goa-1.0.gir             Soup-2.4.gir
EBookContacts-1.2.gir  GObject-2.0.gir         SoupGNOME-2.4.gir
EDataServer-1.2.gir    Gst-0.10.gir            Tracker-0.16.gir
fontconfig-2.0.gir     GstBase-0.10.gir        TrackerExtract-0.16.gir
freetype2-2.0.gir      GstCheck-0.10.gir       TrackerMiner-0.16.gir
Gck-1.gir              GstController-0.10.gir  WebKit2-3.0.gir
Gcr-3.gir              GstNet-0.10.gir         WebKit-3.0.gir
GcrUi-3.gir            Gtk-2.0.gir             win32-1.0.gir
Gda-5.0.gir            Gtk-3.0.gir             xfixes-4.0.gir
GData-0.0.gir          GtkClutter-1.0.gir      xft-2.0.gir
GDesktopEnums-3.0.gir  GUdev-1.0.gir           Xkl-1.0.gir
Gdk-2.0.gir            GWeather-3.0.gir        xlib-2.0.gir
Gdk-3.0.gir            JavaScriptCore-3.0.gir  xrandr-1.3.gir
GdkPixbuf-2.0.gir      Json-1.0.gir

To create docs for Clutter

$ g-ir-doc-tool --language GJS -o ./clutter-docs /usr/share/gir-1.0/Clutter-1.0.gir
$ cd clutter-docs

Inside there you will find several .page files that you can open with yelp. We start with index.page

$ yelp index.page

yelp-index

Clutter Index

yelp-behavior

Clutter Behaviour Scale

There is a way to export the yelp files into HTML with yelp-build tool.

From inside clutter-docs directory

$ yelp-build --help
Usage: yelp-build  [OPTIONS] [FILES]

Commands:
  cache         Create a Mallard cache file
  epub          Create an EPUB file for Mallard
  html          Convert input files to HTML
  xhtml         Convert input files to XHTML

Therefore we can use

$ yelp-build html *

And this will create the HTML pages alongside with some CSS and Javascripts, allowing us to view docs from browser.

html-index

Clutter Index

html-behavior

Clutter Behaviour Scale

I thought to upload those HTMLs somewhere, but since the quality is poor, I skipped it!


 
  We can't watch comments unless G+ provides an API or if you send a notification, e.g +World Of Gnome
     Sometimes is better to place your questions on GNOME Community