In #270263: 1.0: publish the "hostmaster API" once it is frozen we discussed actually documenting the API, and then I went and hijacked the discussion towards getting http://api.aegirproject.org up and running.
I recently discovered the existence of hosting_HOOK_post_hosting_install_task(). There must be others... Currently, hosting.api.php only includes two functions: hook_hosting_service() & hook_hosting_service_type().
As a fairly inexperienced developer, I rely heavily on such resources as api.drupal.org. Hence why I put the effort into getting our own API site up. As a mere mortal, and without the jedi-like grep/regex skills I've seen some of you wield, I'd like to see documenting the API become a priority for a 1.0 release.
Comments
Comment #1
Steven Jones CreditAttribution: Steven Jones commentedSo bad/no documentation is major problem for people, so this is a major issue. It shouldn't stop a release, but should trigger one if this issue gets completed!
I'm going to start compiling a list...
Comment #2
Steven Jones CreditAttribution: Steven Jones commentedAfter a quick find for 'module_invoke' I get:
Which should be a complete list I think, unless there are some other strange ways of calling them.
Comment #3
Steven Jones CreditAttribution: Steven Jones commentedSo, if you're reading this, how can you help?
Well this is all happening in the dev-documentation branch in the git repo, so you'll either want to get that branch or have a look on gitweb.
If you want to write documentation, find a hook above that is marked 'Not documented' and add an issue that provides a patch that documents the hook, or just some words that look like a patch, I can handle the code wrestling for you.
If you want to review documentation, find a hook marked as 'Needs review' and review it! If you like the docs, then reply HERE, saying so, if you have an issue with the docs, create a NEW issue and we'll handle the review over there.
Thanks!
Comment #4
ergonlogicIn Part Two of Mig5's excellent article, there's reference to drush_hook_pre_hosting_task().
I don't see it in the list above, but it appears used in a few places:
Comment #5
Steven Jones CreditAttribution: Steven Jones commentedYeah, so technically those are drush hooks of hostmaster drush commands. I do think they need documenting, but I'm not sure how yet.
Comment #6
Steven Jones CreditAttribution: Steven Jones commentedRight, I've added stubs for all the functions in the table above, so people can create patches more easily.
Comment #7
Steven Jones CreditAttribution: Steven Jones commentedI've merged in the first round of changes into the stable branch, yey!
Comment #8
Steven Jones CreditAttribution: Steven Jones commentedanarcat did some slightly misguided re-organisation and we actually lost a lot our docs, we need to get some issues fixed on the API site, and once we have that in place we can be in a position to fix Aegir's documentation once and for all...
Comment #9
Steven Jones CreditAttribution: Steven Jones commentedOh, this needs to happen badly :)
Comment #10
ergonlogicHmm, a couple more Hostmaster Drush hooks that'll need documenting:
drush_hook_provision_nginx_server_config() defined in Provision_Config_Nginx_Server::process
drush_hook_provision_nginx_vhost_config() defined in Provision_Config_Nginx_Site::process
These hooks are also invoked in the equivalent SSL classes.
Notably absent is the Nginx equivalent to drush_hook_provision_apache_dir_config().
Comment #11
ergonlogicI just found another (so far undocumented?) hook: hook_provision_services(). I'm pretty sure we have it in the example module, though. It's looks like a provision hook, and not one of the standard pre_, post_, _rollback, ones. So, I'm adding it here as a reminder, even if this issue is focused on hostmaster hooks.
Comment #12
ergonlogicIt would also be great to document how things like this work (from Provision_Service_db):
'subscribe_site' is overridden in aegir_basic_auth, for example, but doesn't appear to be called (directly) from anywhere in either the front-end or back-end code.
... A bit more digging turned up the following (from init() in Provision_Context):
I have no idea how to properly document this stuff. But right now, I'm having to work with existing implementations and guesswork.
Comment #13
ergonlogicre. my last post, I found #955018: ability to save new arbitrary data to a context from outside the service which references this great article on the subject: http://www.computerminds.co.uk/articles/storing-data-aegir.
Perhaps we could adapt that text to describe this functionality on the API site, in the way api.drupal.org has guides and references to each of the major subsystems. I think we could do this with static HTML linked from hosting/example/index.php.
Comment #16
helmo CreditAttribution: helmo commentedComment #19
helmo CreditAttribution: helmo as a volunteer and at Initfour websolutions for Aegir Cooperative commentedcopied the table from #2 to be able to edit it.
Comment #20
helmo CreditAttribution: helmo as a volunteer and at Initfour websolutions for Aegir Cooperative commentedworking through the list.
Comment #21
helmo CreditAttribution: helmo as a volunteer and at Initfour websolutions for Aegir Cooperative commentedmost of them we're already there...
Minor updates in http://cgit.drupalcode.org/hosting/commit/?id=52ac5b8
For reference most of these are in these files: