API

Generates and displays API documentation pages.

This is an implementation of a subset of the Doxygen documentation generator
specification, tuned to produce output that best benefits the Backdrop code base.
It is designed to assume the code it documents follows Backdrop coding
conventions, and supports Doxygen constructs as documented on
https://api.backdropcms.org/doc-standards.

In addition to standard Doxygen syntax requirements, the following restrictions
are made on the code format. These are all Backdrop coding conventions (see
https://api.backdropcms.org/php-standards for more details and suggestions).

1. All documentation blocks must use the syntax:

   /**
     * Documentation here.
     */
   

   A leading space before the asterisk on subsequent lines is required.

2. When documenting a function, constant, class, etc., the documentation block
   must immediately precede the item it documents, with no intervening blank
   lines.

3. There may be no intervening spaces between a function name and the left
   parenthesis that follows it.

Besides the Doxygen features that are supported, this module also provides the
following features:

1. Functions may be in multiple groups (Doxygen ignores all but the first
   group). This allows, for example, theme_menu_tree() to be marked as both
   "themeable" and part of the "menu system".

2. Function calls to PHP library functions are linked to the PHP manual.

3. Function calls have tooltips briefly describing the called function.

4. Documentation pages have non-volatile, predictable URLs, so links to
   individual functions will not be invalidated when the number of functions in
   a document changes.

Installation and setup

See http://drupal.org/node/1516558 for information on how to install and set up
this module.

Views Integration

The API documentation is integrated with Views. Actually, most of the
listing pages for the API module use Views, and you should be able to clone
and modify these pages to make your own views if you want something different.

Search Integration

If you enable the included "API Search Integration" module (machine name:
api_search), as well as either the Backdrop Core "Search" module or the
contributed Apache Solr search module, you can perform full-text searches
on API documentation, just like your regular site content.

Configuring Core Search

1. Enable the Core Search module and the included "API Search Integration"
   module.

2. Visit the API search configuration page, and choose which Core
   Compatibilities to index (on admin/config/development/api/search).

3. If you already had core Search and the API module installed and running on a
   site, and then enabled the "API Search Integration" module later, you will
   either need to run a reparse of the API documentation, or a reindex of Search,
   in order to get the full text of the API documentation into the search index.
   But if you already had Search but not API, or API and not Search, and then
   enable the other one plus the search integration module at the same time, the
   API documentation will automatically be indexed for you over the next cron
   runs.

In either case, once the indexing is complete, you'll be able to do full-text
searches of API documentation under the "Content" search tab (along with other
node content on your site).

Configuring Solr Search

This is a little more involved. Assuming you already have the Apache Solr
module configured and working, and optionally the Facet API module,
here are the steps:

1. Install/enable the included "API Search Integration" module.

2. On your Solr configuration page (admin/config/search/apachesolr), at the
   bottom under Configuration, check "API reference entries" under Node, to
   make Solr index API reference information.

3. Visit the API configuration page, and choose which Core
   Compatibilities to index (on admin/config/development/api/search).

4. Run cron until the index is complete.

5. If you want to do faceted search, on
   admin/config/search/apachesolr/settings/solr/facets
   set up the Branch, Project, Core Compatibility, and Object Type facets (or
   some subset). If your search is mixing API items with other nodes on the
   site, you may also want the "Content type" facet enabled. API nodes will
   show up as content type "API Documentation".

6. On the Blocks page, turn on blocks for your search box and facets. If you
   also have the API module's "Search" block enabled, you may want to change
   the Search block title to distinguish between full-text full-site search and the
   search for exact object names in the API module.

7. You will probably also want to do the following, on
   admin/config/search/settings :

• Make Apache Solr search the only search module
• Make Apache Solr search the default search module

8. You may need to set up permission "Use search" for appropriate roles.

License

This project is GPL v2 software. See the LICENSE.txt file in this directory for
complete text.

Maintainers

This module is currently seeking maintainers.

Credits

Ported to Backdrop CMS by Nate Haug (https://github.com/quicksketch).

The bulk of this module was written and is maintained in the Drupal project
(https://www.drupal.org/project/api) by:

• Neil Drumm (https://www.drupal.org/u/drumm)
• Jennifer Hodgdon (https://www.drupal.org/u/jhodgdon)

This module also currently bundles the "grammar_parser" Drupal library
(https://www.drupal.org/project/grammar_parser) that was written and is
maintained by:

• Jim Berry (https://www.drupal.org/u/solotandem)