Allow multiple, partitioned paths to be indexed
| Project: | API |
| Version: | 6.x-1.x-dev |
| Component: | Code |
| Category: | feature request |
| Priority: | critical |
| Assigned: | drumm |
| Status: | active |
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
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
#3
Added project and branch_id to {api_branches}. Now the other tables need branch_name changed to branch_id.
#4
There's a typo in update 20.
#5
Already fixed from another issue. Keeping this active since more cleanup is needed.