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

Assigned:Unassigned» Steven Jones
Priority:Normal» Major

So 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...

Status:Needs work» Active

After a quick find for 'module_invoke' I get:

Hook Defined in Status Issue
hook_nodeapi_TYPE_OP hosting_nodeapi Needs review Add
hook_allow_domain hosting_domain_allowed Needs review Add
hook_hosting_queues hosting_get_queues Not documented #1113560: Document hook_hosting_queues
hook_provision_args hosting_queues_get_arguments Not documented #1113508: Document hosting_queues_get_arguments and hook_provision_args
hook_hosting_TASK_OBJECT_context_options drush_hosting_task Needs review Add
hook_hosting_TASK_TYPE_task_rollback drush_hosting_hosting_task_rollback Needs review #1113858: Document hook_post_hosting_TASK_TYPE_task
hook_post_hosting_TASK_TYPE_task drush_hosting_post_hosting_task Needs review #1113858: Document hook_post_hosting_TASK_TYPE_task
hook_hosting_quota_resource hosting_quota_admin_client_list Needs review #1113872: Document hosting_quota module
hook_hosting_quota_resource hosting_quota_admin_defaults_form, hosting_quota_get Needs review #1113872: Document hosting_quota module
hook_hosting_tasks hosting_available_tasks Needs review Add
hook_hosting_service_type hosting_server_services Needs review Add
hook_hosting_service hosting_server_services Needs review Add
hook_hosting_site_options_alter hosting_site_available_options Not documented Add
hosting_TASK_SINGULAR_summary hosting_queue_block Not documented Add
hosting_TASK_SINGULAR_list hosting_queues Not documented Add
hosting_QUEUE_TYPE_queue hosting_run_queue Not documented Add
hosting_task_TASK_TYPE_form hosting_site_list_form, hosting_task_confirm_form Not documented Add
hosting_task_TASK_TYPE_form_validate hosting_task_confirm_form Not documented Add
hook_drush_context_import hosting_drush_import Not documented Add

Which should be a complete list I think, unless there are some other strange ways of calling them.

Status:Active» Needs work

So, 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!

In 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:

./site/hosting_site.drush.inc:50:function drush_hosting_site_pre_hosting_task($task) {
./clone/hosting_clone.drush.inc:4:function drush_hosting_clone_pre_hosting_task($task) {
./alias/hosting_alias.drush.inc:4:function drush_hosting_alias_pre_hosting_task() {
./migrate/hosting_migrate.drush.inc:4:function drush_hosting_migrate_pre_hosting_task($task) {
./package/hosting_package.drush.inc:4:function drush_hosting_package_pre_hosting_task() {

Yeah, so technically those are drush hooks of hostmaster drush commands. I do think they need documenting, but I'm not sure how yet.

Right, I've added stubs for all the functions in the table above, so people can create patches more easily.

I've merged in the first round of changes into the stable branch, yey!

Status:Active» Needs work

anarcat 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...

Version:6.x-0.4-alpha3» 6.x-2.x-dev

Oh, this needs to happen badly :)

Hmm, 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().

I 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.

It would also be great to document how things like this work (from Provision_Service_db):

  /**
   * Register the db handler for sites, based on the db_server option.
   */
  static function subscribe_site($context) {
    $context->setProperty('db_server', '@server_master');
    $context->is_oid('db_server');
    $context->service_subscribe('db', $context->db_server->name);
  }

'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):

    // Set up subscriptions for the available services.
    $service_list = drush_command_invoke_all('provision_services');
    foreach ($service_list as $service => $default) {
      $class = "Provision_Service_{$service}";
      $func = "subscribe_{$this->type}";
      if (method_exists($class, $func)) {
        call_user_func(array($class, $func), $this);
      }
    }
    return true;

I have no idea how to properly document this stuff. But right now, I'm having to work with existing implementations and guesswork.

re. 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.