Drupal: API

This page is my personal notes about how to set up a Drupal 7 API reference site using the projects API and Examples from Drupal.org.

Table of contents

Introduction

The API project was designed to produce the Drupal developer documentation available at api.drupal.org. It may also be used on other sites. There is currently no version of the project for other versions of Drupal than Drupal 7.

It was used by me to provide ducumentation pages for the website drupalprimer.com. This website is currently not being actively developed and is running Drupal 8 with the Drupal 8 W3CSS Theme.

The module parses source files and extracts call templates along with the Doxygen marked up text in comments to produce documentation pages.

RealityLoop has created a profile (named DrupalAPI), but it is buggy and outdated, and contains a lot of surplus marketing material. It is OK to get a general feeling of what the API project can do, but not suitable for production.

This note is about setting up this from scratch, using project API.

This is how this is utilised on the web:

Main documentation:

Projects that form the basis of this feature on DrupalPrimer.org:

The rest of this notes gives a step by step recipe for setting up a site with an API reference in place.

Download and enable components

Required modules and libraries:

  1. Ctools
  2. Views
  3. Libraries API (branch 7.x-2.x)
  4. Grammar Parser project (branch 7.x-2.x). Install it below sites/all/libraries.
  5. Grammar Parser library API (branch 7.x-2.x). Install it below sites/all/modules.
  6. API (branch 7.x-1.x)

I use the bleeding edge 7.x-2.x branch of the Grammar Parser project and the Grammar Parser Library. These two must be in sync, but work OK with the 7.x-1.x branch of the API project.

This is simplest done with drush. Note some of the components requires non-default versions. Check the project pages to make sure you specify the right one. Also the API module requires a lot of scaffolding, so download and enable that as well.

drush dl api -y
drush dl examples -y
drush dl ctools -y
drush dl views -y
drush dl libraries -y
drush dl devel -y
drush dl token -y
drush dl grammar_parser-7.x-2.2 -y
drush dl grammar_parser_lib-7.x-2.1 -y
mv grammar_parser/ ../libraries/grammar_parser/

drush en ctools -y
drush en views -y
drush en views_ui -y
drush en gplib -y
drush en api -y
drush en devel -y
drush en token -y

If you want to allow comments, make sure the core Comment module is turned on.

Make sure the following blocks are visible:

Put the source material in place

The source for the material that goes into the API sites comes from from the following three projects:

The first are already in place as part of the site, the last (Documentation) doesn't have a release, so it has to be pulled with git. However:

  1. The Documentation project include a lot of fluff that eats resources.
    • Documentation: documentation/marketing
  2. Using git to download the material means that there will be a full git repo associated with it.
    • Documentation: documentation/.git
  3. The root documentation page needt be be customized for Drupal Primer.

Ignore:

The solution is a small shell script to update (getapi.sh) that clones the Documentation project and then deletes and fluff and the git repo, and replaces the root documentation page. Run this script before generating the API views and indexing them. (Reindexing takes a long time. May consider keeping git repos to speed up updating.)

After manually updating the root documentation page (or any other page), run update on the branch to get the changed file regenerated and reindexed.

Set up the API reference sub-site

Navigate to Config → Development →API reference. There are five tabs, but for a standard site, you only fill in the first three to initiate a reference sub-site.

Below is a brief description of all five tabs, as well as typical settings for the first three.

Overview (tab 1)

The settings under this tab allow you you set the default core compatibility and the name of the default project (typical settings in brackets):

The page under this tab also present a report with a overview over the queues that are active when the reference files are parsed and indexes:

Projects (tab 2)

Gives overview of defined projects, where a project is anything you want to appear as a project when projects are listed, it may be a the Drupal Core, a single module, theme, or any other group of files that the API module is parsing. You may group files from several Drupal projects in a single API project.

When defining a new project, you need to fill in the following three fields (typical settings in brackets):

Currently, the following three projects exists:

Branches (tab 3)

Within a Project, a branch is particular version of the files (6.x-1.x, 7.x, 7.x-1.3, etc.). Note that core compatibility should be a single integer, not a branch identifier. The branch identifier can be a full branch identifier or an integer.

This tab let you edit, reparse, update, or delete a branch.

The reparse link forces a parse of every file in the branch.

The update link sets a flag that forces a scan of the file directories in the branch for updated and removed files on the next cron run. By default this only happens after a minimum time (branch update frequency) has passed. There is no need to click this if the branch update frequency is set to 1 second (cron will do). Use this link to force changed reference pages re-built if the Branch update frequency is long.

Typical settings:

When you create or edit a branch, you get to list the root directories to parse. My current setup for Drupal Primer is have the following two branches:

d7core

Directories:

/www/drupalprimer.com/htdocs

This should also parse the ref/ subdirectory.

Exclude directories:

/www/drupalprimer.com/htdocs/sites
/www/drupalprimer.com/htdocs/modules/simpletest/tests

examples

Directories:

/www/drupalprimer.com/htdocs/sites/all/modules/examples

Other settings:

The Branch update frequency fields sets a minimum time to wait before checking for branch updates. Drupal will not bother parsing the branch to see if there are any updates that need to be re-parsed before this time has elapsed. Checking takes a long time, so setting a high frequency will slow down your site during cron runs.

Reference branches (tab 4)

This tab is used to define a website that is used to make links to externally-defined functions (such as making links to php.net for the built-in PHP functions).

Use the following settings:

http://svn.php.net/repository/phpdoc/doc-base/trunk/funcsummary.txt
http://php.net/manual/en/function.!function.php
(I've no idea about how these may be accessed.)

Comment settings (tab 5)

To administer miscellaneous comment settings.

Enable and index

Documentation is indexed during cron runs. Unless you're prepared to wait a long time, run cron manually.

Progress indexing the site can bee seen under Search settings.

Configuration

The API reference root should now be present with the path /api.

Change the italics according to your node object and the content type machine readable name.

Still a mystery what goes where.

Upgrades

Some care must be exercised not to break anything during upgrades.

Minor core upgrades

Use CLI script drupal_update.sh. Check that api comments are not zapped by the upgrade by examining hook_enable.

Upgrades of contributed materials

To upgrade the API project:

drush dl api -y

To upgrade the Grammar Parser Library interface:

drush dl grammar_parser_lib-7.x-2.1 -y

To upgrade the Grammar Parser:

drush dl grammar_parser-7.x-2.2 -y
mv grammar_parser/ ../libraries/grammar_parser/

Tables

Imortant URLs

The fields below are: relative URL | Navigation menu | Title | API Navigaton.

Theming

Some of the tables are very wide. Theme should allow for use of full width and have to right sidebar.

Candidate theme: Platon.

Troubleshooting

Text in comments on API pseudo-nodes can not be found by site search.

Do the comments added to API nodes disappear after a core upgrade? I am so far been unable to determine what causes this (minor upgrades the the core does not seem affect it.) Seven comments where added after upgrade to 7.30 on 2014-08-03. They are still around after upgrade to 7.31 on 2014-08-11.

Doxygen notes

The Drupal.org documentation of its Doxygen dialect is here. The notes below is to augment this.

The first string in the @link … @endlink tag can be:

The rest of tag becomes anchor text.

Below is an example of how these tags may look like:

/**
 * @link check_plain function name example @endlink
 * @link DatabaseConnection class name example @endlink
 * @link MAINTAINERS.txt file name example @endlink
 * @link sanitization group identifier example @endlink
 * @link https://drupal.org/project/examples external URL example @endlink
 * @link /api/globals/7 internal URL example @endlink
 */

In the API documentation, the group identifier appears after the word “group” in URLs. Example:

http://example.com/api/d7core/drupal!includes!common.inc/group/sanitization/7

Last update: 2015-02-13 [gh].