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
- Download and enable components
- Put the source material in place
- Set up the API reference sub-site
- Enable and index
- Configuration
- Upgrades
- Tables
- Imortant URLs
- Theming
- Troubleshooting
- Doxygen notes
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.
- RealityLoop.com: video
- Profile DrupalAPI
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:
- API – project API reference
- Drupal – the official core files
- Examples – project Examples for developers
- Documentation – main project for all user contributed documentation
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:
- Ctools
- Views
- Libraries API (branch 7.x-2.x)
- Grammar Parser project (branch 7.x-2.x). Install it below
sites/all/libraries
. - Grammar Parser library API (branch 7.x-2.x). Install it below
sites/all/modules
. - 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:
- API Navigation
- API Search
Put the source material in place
The source for the material that goes into the API sites comes from from the following three projects:
- Drupal – the official core files
- Examples – Example modules for developers
- Documentation – main project for all user contributed documentation
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:
- The Documentation project include a lot of fluff that eats resources.
- Documentation:
documentation/marketing
- Documentation:
- Using git to download the material means that there will be a full git repo
associated with it.
- Documentation:
documentation/.git
- Documentation:
- The root documentation page needt be be customized for Drupal Primer.
Ignore:
- Drupal:
drupal/modules/simpletest/tests/upgrade
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
. 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):
- Default core compatibility: (7)
- Default project: one of the projects defined under the tab (just leave this blank).
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:
- File parse – the remaining number of files discovered in branches, but not yet parsed for display, decremented each time cron is run.
- Batch update – scans branches for files that have been updated or removed, and adds jobs to the file parse and node cleanup queues.
- Node cleanup – deletes nodes for removed files.
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):
- Identifier: unique identifier, used as machine name, for project path (d7core)
- Title: Used to identify the project in lists (D7 core API reference).
- Type: Type of project (core, module, theme, etc.).
Currently, the following three projects exists:
- d7core
- reference
- examples
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
or a branch.The
link forces a parse of every file in the branch.The
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:
- Project: (must be defined, e.g.: d7core)
- Core compatibility: (7)
- Preferred: (yes?)
- Branch identifier: (7)
- Branch title: Used for menu item and root page title (API reference)
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:
- Exclude directories: (none, unless listed above)
- Exclude files by regular expressions: (none)
- Branch update frequency (test: 1 second; production: 1 week)
The
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
.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
api_branch
– Holds project branches.api_documentation
– Holds the contents. Field did corresponds to nid in the node table. Field title is the display title when the piece is displayed.api_external_documentation – Holds reference branches.
node
– There is a pseudo-node for each piece of documentation, but the title field is empty. However, it may be used as a permalink to the node: http://www.drupalprimer.com/node/15298.
Imortant URLs
The fields below are: relative URL | Navigation menu | Title | API Navigaton.
- api/d7core | Api reference | API reference | BRANCH API reference
- api/examples | - | API reference | BRANCH Examples
- api/examples/examples.module/group/examples/7 | - | Examples | Examples
- api/examples/examples.module/group/examples/7 | - | Examples | Examples
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.
- Using
drush cron
provides better diagnostics. - If you run out of memory during indexing (i.e. cron runs), ensure
that your PHP
memory_limit
is set high enough. You can find out how much is required by setting it very hight and enabling Memory profiler. You'll find the memory consumed in the watchdog log (currently around 319 Mbyte). To increase the memory limit for a vhost, change the setting in its configuraton file and restart the web server. See also: Changing PHP memory limits. - If the the path /api doesn't work and API navigation block does not appear, check the setting of the core compatibility field. Source: https://drupal.org/node/1635974.
- Changed pages may not be updated when cron runs, even when queued for parsing if the file parse queue isn't empty. When debugging, adjust paths to have a short queue.
- If changed pages still aren't updated when cron runs, make sure the system clock (date) is accurate.
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:
- function name
- class name
- file name
- group identifier
- URL
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].