make api.module aware of .info files
| Project: | API |
| Version: | 6.x-1.x-dev |
| Component: | Parser |
| Category: | feature request |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | active |
I've just spent (quite) a while trying to build in the ability to list and browse by module for my own contrib mirror.
Currently it's been quite frustrating because I can only find things by : searching, clicking to a function name, clicking back to the containing file, scanning the functions in that file. :-/
This also misses out on module extras declared in .inc and related files.
I could almost do it by defining each module as a topic/group, but that seemed lots of busy-work, and we've got .info files there already, being ignored.
I just want:
- a list of module names
- - a list of documented items within that module
Much more browsable.
Soo... So far I've been able to:
- Define a new object type 'project' ... because drupal.org/projects include modules, themes and profiles, and each has a .info file, and I can't tell the difference between themes and projects
- Get *.info files scanned and parsed, creating new items, very much like a 'file' or 'group'.
- Create a new page callback that lists them!
- Create individual pages for each info item, displaying a small amount of info extracted from the file. :-)
Pretty good.
But I'm having trouble linking the project/info overview with its content items. Clearly I'd want my project/module to have references to all the contained files and functions (and docs and templates).
Also the theme_ functions collected as special module-docs would be very good!
I can't quite trust just linking all files in the same folder as the info file as members of that project. It's probably right, but not always, in the case of packages. Still, I can live with some false positives.
I can't trust function name prefixes either.
What I'm wondering is
- Does anyone know how I should better establish these references?
- Should I make these references in the database at scan time (and is {api_reference_storage} appropriate for that job)
- or should I do a reverse lookup based on filepath when rendering the project page.
Is this just too hard? I've gone a long way in patching this in... but am stuck at this point where it's all supposed to come together.
Ideas?
#1
You've just encountered a problem with how to consider which files are part of which 'modules'. For instance, your module directory has a sub-folder 'includes' that is used by one or more of the sub-modules. Which 'module' does the includes folder belong to? We can use this same logic with core's own /includes directory, which doesn't belong to any module.
#2
Yes, it would be good to do all of this and I don't think it is too hard of a problem. {api_reference_storage} exists to store references to code that hasn't been parsed yet. This probably isn't needed here, info files have important enough information to justify making sure they get parsed before the rest of their directory. But if the data structure fits well enough, then use the table, I'm not sure that it does.
Please post your existing code, being aware of projects is a major gap in the API module now.
#3
Here's the patch so far. (not sure how to roll a unified patch including a new file)
I'm still finding my way around (patch may be scratchy), but have basically emulated the existing behaviours to provide a simple 'project' concept.
A 'project' documentation definition contains only a description and dependancies as per the .info.
On display, I'm listing the functions found in the {x}.module file that corresponds to the {x}.info (with code taken from the parse file routine). This is what needs to be improved, but is a start at what I wanted to see.
Maybe the next step is to list the files found nearby as being relevant to the project, though not always part of it. Maybe one day the info files will include a manifest or *.inc registry - theme .infos have already started that.
Good to know that {api_reference_storage} isn't relevant. So basically ALL the logic/structure is pre-parsed, nothing special is done at lookup time. Cool.