Allow multiple, partitioned paths to be indexed

ezyang - February 6, 2008 - 03:01
Project:API
Version:6.x-1.x-dev
Component:Code
Category:feature request
Priority:critical
Assigned:drumm
Status:active
Description

Currently, the API module only allows one "API reference", although it allows multiple directories to be indexed. While this is good for documenting Drupal's core includes and modules, it is unwieldy for use on Drupal's contributed modules, which are numerous and need to be partitioned from the API reference.

The way to fix this is to allow API to manage multiple API references, each of them separate from each other. Some implications of this:

Paths

Currently, API documentation resides in "api/". Sub-API references should likely be placed in "api/modulename/", however, this may cause backwards compatibility problems if modulename happens to coincide with an existing documentation path; "multi-api/modulename" might be a better name.

Cron

One of the primary concerns with generating API docs for drupal-contributions is that it's so big. The cron job for API will have to be careful to queue things so that running cron does not take a ridiculous amount of time. This may not be a problem if we adhere globally to "Maximum files to scan per cron run:"

Schema changes

Basically every table will now need an api_id column added them, so we can keep track of which API segment it manages. That's about it, however, so the conversion would be fairly straightforward.

Branches

The natural way to manage these would be to have each project manage their branches separately. However, for drupal-contributions branching practices will be fairly uniform, so it is tempting to make a common set of branches; however, the combination of Drupal and Module branches will ensure that a common set of branches will not be feasible. Nevertheless, the procedure of adding branches will need to be automated for this to be practical (something that was not necessary for regular Drupal docs).

And of course...

Anything else I might have missed. Any comments?

#1

drumm - August 25, 2009 - 20:29
Priority:normal» critical

To-do:
* Convert branch_name to branch_id
* Add project column to branch table
* Change URLs to {project}/{file}[/object][/branch]. This is done for files and leads to #179062: handle duplicate function names being fixed
* UI to support projects

#2

drumm - October 9, 2009 - 08:11
Assigned to:Anonymous» drumm

#3

drumm - October 15, 2009 - 05:54

Added project and branch_id to {api_branches}. Now the other tables need branch_name changed to branch_id.

#4

Darren Oh - October 26, 2009 - 03:46
Version:HEAD» 6.x-1.x-dev
Status:active» needs review

There's a typo in update 20.

AttachmentSize
api.install-218306-3_D6.patch 768 bytes

#5

drumm - November 7, 2009 - 20:22
Status:needs review» active

Already fixed from another issue. Keeping this active since more cleanup is needed.

 
 

Drupal is a registered trademark of Dries Buytaert.