Hook_sitedoc

Thanks for opening this. I probably should have done that myself. The statement in the documentation is vague because the requirement is still vague. It stems from Webchick's suggestion in the group and another post here to:

...one other thing I really want to do is make this module "hook-able" so that I could, for instance, write an .inc file to export OG information, or Actions/Workflow information... these wouldn't make sense for sites that don't have those modules, but would be very valuable for those that do.

I have some ideas on how to interface Sitedoc with other modules, but really am having trouble deciding exactly what another module might want displayed in the output. I could see some cases where a particular module's settings might be important enough to document here, but not in most cases (they are largely represented in the variables).

In Webchick's suggestions, perhaps Actions might want to document specific actions that are in play. Or possibly, something like Update_status might want to include a list of outdated modules (or would this be better merged into the module list?).

So I see the main questions being:

1. How do we describe what a module developer might want to include? Or shouldn't?
2. How would that information be returned (or included) in a flexible way that is "easy" for any module to provide? [My first thought is to use an array and process it much like I do the variables.]
3. Should this information be placed with the module in the modules list, or should it be a separate section for each one?

I think you could create a section for each module. I've downloaded your module but haven't played with it yet. Do you have multiple pages, or are things in fieldsets? I imagine you could have a single page for all of the hooked modules and have their info in collapsed fieldsets. If most data can be expressed in tables, then I think you could simply as for either the html as generated by a theme function that uses theme_table, or for the header, rows, and (what else is there?) that your hook would then render.

I agree that many modules have info that is contained in the variable table. This hook of yours would primarily be useful to those that keep their own tables. Most of my modules do. I've got accounttypes, og_content_type_admin and og_multiple_mandatory_groups_by_role which all do. Plus I have a couple non-public ones as well and more of both to follow. These modules I mention all relate to other modules, so I imagine I would like to show those relationships. I guess I do that already within the admin interfaces, but I think that's the kind of thing you're looking for, is it not?

For example, in og_content_type_admin, potentially every OG on the site can have different content types ALLOWED, ACTIVATED, and REQUIRED (or their counterparts DEACTIVATED and NOTREQUIRED). And accounttypes are associated with roles, as are mandatory groups in my other module.

So that's my first idea. I'll give it more thought.

Well, I would suggest you go ahead and try it out. That way you can see how things might fit in. I definitely agree that things like relationships that are important and not represented other ways should show up.

Okay, it'll be a little while (1-2 weeks) before I get a chance to try this out. I've been given CVS access to the og_forum project and am embarking on a clean-up job to get things ship-shape over there. So when I'm done, I'll try my idea. Cheers.

Here's my thinking: The modules called will provide back an associative array that contains a key and a value. There can be more than one key passed back. The value may itself be an array is the same format. By using this format, I can reuse the table code that formats the variables table, which is recursive and can go many levels deep (for example, if you use the Garland theme, look at its variables). In the simplest form, there would be a simple table with keys and values.

For guidelines to determine if a module provides this hook, how about something along the lines of: "If you have settings or other data that is important for a new webmaster or auditor to know upon taking over or reviewing a site, it should be listed." For example, a module like Update Status might want to add in information on modules that are out-of-date or have unapplied security fixes. As an example of conditional inclusion, the Site Documentation module might want to report that it's running Cron and some of the "fixer" options are on, otherwise it would return null.

Oops, I never got around to this. I'm bumping it so it shows higher on my "My issues" page. I have had deadlines on my plate and although I'll love to put this in my modules, haven't had the chance to play with it yet.

This will probably wait until a D6 release, unless my "hooks implemented patch" spurs me to more fully develop this.