This is a demo site specifically developed to show the capabilities of the silverstripe-gtkdoc module. To access the code and submit bugs or feature requests, please go to the developer section. The code is maintained in a public git repository and is available also on GitHub.

Sample view of a typical silverstripe-gtkdoc use caseThe three reference manuals reported here (GLib, GObject and GOffice) are only samples put together to show how the final result should appear. They are not intended to be used for consultation and will not be kept up to date. For this task there is the GNOME developer center.

What is silverstripe-gtkdoc

The silverstripe-gtkdoc module implements a new page type (Gtkdoc) that allows to import into the pages tree of a SilverStripe based website a reference manual generated by gtk-doc.

A Gtkdoc page is a typical page (a SiteTree instance) and can contain arbitrary text. The reference manual will be shown as a tree of (virtual) subpages underneath that page. Althoug not visible from the CMS in the pages hierarchy, those subpages are indexed and are accessibles from the templates or from the search results. For better results it is suggested to use a theme that is cabable of rendering menu at arbitrary nested levels, e.g. silverstrap or silverstripe-treeish.

Setting the absolute path to the .devhelp2 fileA new parameter is required in order to identify the reference manual to include: the absolute path to its .devhelp2 file. It must be specified into the CMS, under the Content tab. The module expects all the html files referenced by the devhelp file to reside in the same path, as usually done by the installation step of a standard gtk-doc based documentation.

The HTML code is picked up directly from the file system. The usual place where reference manuals are installed is under /usr/share/gtk-doc/html/ (typical case on GNU/Linux platforms) or /usr/local/share/gtk-doc/html/ (on BSD based systems). The chunk of HTML to render in the templates must be extracted and converted from the HTML file: the chunks are cached in the database under the GtkdocSection table. The timestamps of the files are checked against the creation date of the GtkdocSection rows at every request to eventually regenerate the HTML chunk when they are not up to date.

How to use it

This is a classic SilverStripe module so if you have a working SilverStripe website and need to include reference manuals just install it in the usual way: unpack the tarball (or get it from the git repository) in your root website and visit the http://yoursite/dev/build/ link. You will be able to add Gtkdoc pages from the CMS. Obviously you also need to have the reference manuals present in the filesystem and they must be readable from PHP.

If you are starting from scratch, you need to deploy a SilverStripe website with the appropriate dependencies.

Real case study

This website (http://gtkdoc.entidi.com/) will be used as a sample deployment of the silverstripe-gtkdoc module. You need to have:

  • SilverStripe 3 (required)
    You could install it in the official way or use the sample tarball provided and follow these instructions. The published website uses silverstripe-3.0.5 but any version equal or greater than 3.0.0 should be fine.
  • silverstrap (recommended)
    The default SilverStripe theme (simple) does not support arbitrary nested levels in the menu but silverstrap does. You could use any other theme supporting deep nesting (such as silverstripe-treeish) or even a standard theme if you do not expect to access the reference manual subpages from the menu, i.e. if you provide your own interlinking infrastructure or if you do not have nesting in your reference manual.
  • silverstrap-cerulean (optional)
    This is a mere aesthetic variation to the silverstrap theme that uses cerulean instead of the default bootstrap theme.
  • silverstripe-autotoc (optional)
    A quite handy module that generates the table of contents dynamically from the HTML content of a page.

Installation steps

To quickly get up and running by using a sample implementation, follow these steps.

  1. Download the sample tarball.
  2. Unpack it in a place visible from your web server.
    Eventually configure a vhost to your web root. My convention is to append a .local suffix to the public domain in my development environment and to configure apache to that virtual host. In this case the development URL is gtkdoc.entidi.com.local but you should configure your own environment. Remember to modify main/_config.php accordingly.
  3. Add the missing dependencies.
    The dependencies are not included in the tarball and must be installed separately. Use your preferred method to get them (unpack the tarballs and rename the directories, git clone in the proper place, symlinks to your local copies or whatever) but be sure the web server can access them for reading. You must at least populate cms and framework (from the SilverStripe 3 project), gtkdoc (from silverstripe-gtkdoc module) and themes/silverstrap (from the silverstrap theme). Install the optional dependencies if you want them, that is themes/silverstrap_Page (from the silverstripe-cerulean customization) and autotoc (from the silverstripe-autotoc module).
  4. Configure the assets directory.
    assets/ is the only directory that must be writable by the web server. Modify the owner or the mode to let the user executing the web server write into that directory. A chmod 0777 assets/ will do the trick but will also make the directory writable by anyone.
  5. Prepare the database.
    Create a database and a user to access it, either by using phpmyadmin or any database client you are used to. You should grant all to that user on that particular database (administration privileges are not required though). Ensure to set the credentials you configured in main/_config.php: you must set at least database, username and password.
  6. Populate the database.
    Just visit http://yoursite/dev/build/ to trigger the database population. If the installation and configuration is fine you should see a report of the operations executed.
  7. Enjoy the CMS.
    Go to the frontend (http://yoursite/admin/) and login with the default administrator credentials (Email = username and Password = password). Start creating Gtkdoc pages: after putting a proper absolute path to a .devhelp2 file and publishing it you will magically get the reference manual into your website.

Once you have anything up and running remember to add your own administrator in the CMS and remove the default administrator from main/_config.php.

Troubleshooting

Before reporting issues on the bug tracker, ensure the following assertions are fulfilled.

  1. The .devhelp2 file and its html components must be readable by the web server. This is rarely the case because PHP usually has restricted access to the underlinying filesystem. If you cannot or do not want modify your php.ini, the typical solution is to copy the gtk-doc html directory somewhere inside your web root.