Create your own API 7.x-2.x Site in Drupal 7

This page explains how to use the API module, versions in the 7.x-2.x branch, to build a site.

Introduction

These instructions are for installing the API Module, using version 7.x-2.x, in a Drupal 7 environment, to build a site similar to http://api.drupal.org. Upgrading instructions for previous versions of the API module and/or Drupal are at the bottom of this page.

Note that the API module can parse any documented Drupal code, including contributed modules, independent of Drupal core version. This means the Drupal code you use to run your site need not necessarily be the same as the code you are parsing and displaying. In fact, it is a good idea to keep the code you are parsing and displaying outside of the site running the API module. These instructions are made with that assumption. It also means that although the API module runs with Drupal 7, you can use it to build a site that displays code from Drupal 7, 8, 5, 4.7, etc.

Useful terminology

The following is a list of terms used on this page and within the API module:

project

A module, theme, Drupal Core, or other group of files that the API module is parsing.

branch

A particular version of a project's files (6.x-1.x, 7.x, etc.).

repository

A directory where you store files for a particular branch/project

Reference branch

An external web site that is used to make links to externally-defined functions (such as making links to php.net for the built-in PHP functions or to api.drupal.org for Drupal Core functions).

update (a branch or reference branch)

Scan the branch for updated files, or the PHP reference branch for updated function definitions. Files that have changed since the last time they are parsed will be added to the queue of files to reparse. Updates are normally done during cron runs.

parse or reparse (a file)

Read in a file and save its information in the API module database, for display on the API site (replacing any previously-stored information from a previous parse of the same file). Parsing is normally done during cron runs.

Step 1: Install Drupal and modules

This section assumes you want to have a new Drupal installation for your API site. If you want to use an existing Drupal 7 installation, skip the download/install Drupal steps.

Requirements note: Some features of the API module require PHP version 5.4 or higher, and the API module will not run without it. Also you need Drupal 7.50 or later for some features to work optimally.

1. Make sure Composer is installed. See the docs section https://www.drupal.org/docs/develop/using-composer for details.
2. Make sure Drush is installed (see http://www.drush.org/en/master/ for details). You may need to update to a recent version that is aware of Composer, and you may experience problems due to library incompatibilities, depending on how Drush is installed (see the Troubleshooting page for details on that).
3. Download Drupal 7 (7.50 or later) at: http://drupal.org/project/drupal
4. Install Drupal. See: http://drupal.org/getting-started/install.
5. Use the following Drush commands to download and enable several needed modules (you may see an error here about compatible versions of Drush; if so, update Drush):
   

   drush dl composer_manager
   drush en composer_manager
   drush dl ctools
   drush dl views
   drush dl api  
   drush en api
   

6. If your site will be using comments, it is also recommended to download and enable the Comment Fragment module. (The reason is that the API module generates fake content items in order to enable comments, and the default URL for single comments does not display API pages well. The Comment Fragment module disables the default comment URL and redirects such URLs to the regular node page instead, which the API redirects to the corresponding URL for the API page.)
7. If the Drush commands did not already download extra packages via Composer, run Composer install to get these external dependencies -- see https://www.drupal.org/node/2405805 for more information:
   

   cd sites/default/files/composer
   composer install
   

8. Change permissions for the API module as needed at: admin/people/permissions

Step 2: Set-up code "repositories"

Once you have Drupal and the modules installed, you need to download some code to parse and display. There are many ways to do this; here we illustrate how to download the Drupal 7 Core code base using Git (with notes on how to download other code and using other methods).

Note: If you are setting up a site for a contrib project, you no longer need to get Drupal Core -- you can have your site link to api.drupal.org instead -- see the section on reference branches in the "optional" steps section below. But you'll still need to set up a repository for the contrib project you're trying to display API documentation for.

1. Create a place for your code to go. It needs to be in a place that your web server can access (i.e., within your web document root). Command line for this:
   mkdir -p /path/to/your/code/repos/
cd /path/to/your/code/repos/
2. Create a subdirectory for the Drupal 7 Core code (or whatever other code you want to display). Command line for this:
   mkdir drupal-7; cd drupal-7
3. Get the most recent version of the Drupal 7 code base (see Version control instructions for Drupal 7.x and the Git handbook for help). If you want to display code from some other project or branch, you can find the relevant git clone command by going to the project page and visiting the "Version control" tab).

   Here's the command to get the Drupal 7 code from Git:
   git clone --recursive --branch 7.x http://git.drupal.org/project/drupal.git

4. As an alternative to the previous step, if you don't want to use Git to keep the code updated, you could also just download the Drupal 7 tar.gz or zip archive from http://drupal.org/project/drupal and unpack it into your repository area (or another project's code from its project page).
5. Get the extra developer documentation using Git from the "Documentation" project (http://drupal.org/project/documentation), and put it in a separate directory. In Drupal 7, this includes the global variable documentation, the Form API reference, and the API documentation landing page. In Drupal 6, it also contains hook documentation. In Drupal 8, it's just the Form API reference. Here's an example command for Drupal 7:
   git clone --recursive --branch 7.x-1.x http://git.drupal.org/project/documentation.git

Repeat these steps to create repositories for Drupal 6, Drupal 8, other projects, etc. Put each branch of each project in its own directory.

Note: The API module will not index code in "hidden" directories (directories whose names start with "."). It also skips directories called "CVS", as it scans your directories and their subdirectories.

Step 3: Set-up API module to index code in repositories

The last required step is to tell the API module where your code repository is, by setting up a "project" and a "branch", and then indexing the code so it can be displayed. The API module has concepts of "projects" and "branches". Projects correspond to projects on Drupal.org, such as "Drupal Core", "Views", "Zen Theme", etc. Branches correspond to major versions within a Project, such as "7.x" or "7.x-2.x". In the API module, a code repository is designated as a "branch". Here's how to set that up:

1. Go to the site you set up in Step 1, and add a new Project at: admin/config/development/api/projects/new (you can navigate to this page starting from the admin/config "Configuration" page in your Drupal site -- it's in the Development section under "API reference"). Fill in the form with the short name of the project (zen, views, drupal, etc.), and the human-readable name (Zen, Views, Drupal Core, etc.). For the Type field, enter module, theme, core, etc. Save the new project.
2. Click on the Branches tab, and add a new branch (at admin/config/development/api/branches/new). Fill out the form with the following values:
   

   Project

   The short name of the project you created in the previous step.

   Core compatibility

   6.x, 7.x, etc.

   Preferred

   If you are going to include multiple branches within the same core compatibility (e.g., Views 6.x-2.x and 6.x-3.x), mark only one of them as "preferred".

   Branch Identifier

   This is an identifier for this branch within this project, and is used as a URL suffix and in other places. Use "7", "7.x", "7.x-2.x", etc.

   Branch title

   This should include the project name, since it has to stand alone in breadcrumbs and link titles. So it should be something like "Drupal 7", "Views 7.x-3.x", etc.

   Directories

   This is a list of absolute paths to the place(s) where your code is. This is where we put in the value from Step 2, such as /path/to/your/code/repos/drupal-7. You can also exclude specific subdirectories by filling out the Exclude Directories field, and exclude files and directories by regular expression by filling out the Regular Expressions field (version 7.x-1.2 and later only). If you are making a Drupal Core branch and you want to include the Documentation repository, put the location of your main Drupal repo on one line, and the Docs repo on another line, in the Directories box.

   Update frequency

   The API module, during cron runs, checks branches to see if any files have changed since the last time they were parsed. If you plan to have a lot of projects and branches on your site, you might want to set the update frequency to a longer time, so that not every branch is checked for updates during each cron run.

   Click Save Branch.

3. On the Overview page, make sure that your default project and core compatibility are set correctly.
4. Optionally (recommended!), edit the "PHP Reference" branch, and set its update time to a longer time (e.g., one week instead of one second). This will ensure that php.net is not checked for updated PHP functions every cron run (which is a waste of time).
5. Process the queue to index the branch. You can do this in any of the following ways:
   • Install Queue UI, and use its UI to process the 'api_parse' queue.
   • Run cron (from admin/config/system/cron) until your new branch is indexed. You can monitor the parsing status of your site on the Overview tab. You can also see which parsing and branch update jobs have run in the Recent Log Entries report (assuming you have the Database Logging core module enabled).
   • If you use drush, you can use drush cron to run cron, and if you have a new-enough version of Drush, you can use drush queue-run api_parse --time-limit=120 to run the parsing jobs.
6. If the queue counts displayed by the script or on the Overview page are not down to zero, run the script or cron again until all the parsing is finished.
7. Go to your new api documentation at path: api. The content should resemble the content at http://api.drupal.org.

Optional steps

• Enable the API navigation and search blocks at: admin/structure/block
• If you are setting up an API reference site for a contrib project (module, theme, etc.), and you want to make Drupal Core functions turn into links, you have two choices: (a) you can set up a project/branch for the Drupal Core code, as described above, or (b) you can set up a "reference branch" that will make Drupal Core functions turn into links to api.drupal.org. To set up a reference branch, go to the "Reference Branches" tab in the API module admin section, (admin/config/development/api/php_branches), and click "Add new API reference branch" (admin/config/development/api/php_branches/new_api). The help under the fields should get you going... You will need to set up one of these for each core compatibility on your site, and during the next cron run, it will be updated to make the links.
• You might want to turn off the "poor man's cron" functionality that is turned on by default in Drupal 7, because API cron jobs can take quite a while, and it might interfere with page loads. You can do that at path admin/config/system/cron (the "run cron every" setting). Of course, you'll need to set up an external cron job if you do that.
• Use the steps above to create repositories, projects, and branches for Drupal 6, Drupal 8, contributed modules, etc.
• By default, Drupal runs queued jobs during cron runs (the API module uses the Drupal queue for all of its branch updates and file parsing). As an alternative (or in addition), you might look into one of these contributed modules for queue management:
  Advanced queue
  Queue UI
  Drush Queue
• The API module has Views integration, and views are used to generate many of the listing pages in the API module. You can modify (carefully!) the default views provided by the API module, or create your own pages using Views. Keep in mind that you may need to use Relationships to display some types of information.

Upgrading from Drupal 6

If you want to update an existing Drupal 6 API site to Drupal 7, it should work just like updating any other Drupal 6 site to Drupal 7. Here are a few notes about the specific contributed modules (besides what is in the Step 1 installation instructions above):

• You will need to update the API module to version 6.x-1.9, and run update.php to get all the database updates, before attempting to upgrade to the Drupal 7 version. If you were running an old version of API (1.6 or earlier), read the release notes for version 1.7 about needing Drupal Queue.
• After doing that, you should be able to wipe out the Drupal 6.x code, including modules, and follow the steps in the first section above to download Drupal 7.x and required modules, and then run the update.php script to update the Drupal database.

Updating from previous 7.x versions

To update from an earlier Drupal 7.x branch to the 7.x-2.x branch, you will need to do the following (refer to the installation steps and notes at the top of this page for more details about each step):

• Update Drush and Drupal core to compatible versions if necessary.
• Disable the old version of the API module, but don't uninstall it.
• Download and enable the Composer Manager module using Drush.
• Get the new version of the API module. Enable it using Drush, and make sure that composer downloaded the required modules.
• Run the update.php script to update the Drupal database (as you always need to do when you update a module version).
• Disable and uninstall modules that are no longer needed, such as Libraries. Refer to the instructions for the 7.x-1.x stable branch of the API module to compare the requirements there to the current requirements.
• Remove the Grammar Parser library from sites/all/libraries, and unneeded modules from sites/all/modules.