On http://drupal.org/node/477684 there is documentation about drush. But why don't we use drush itself to generate the definition lists of the commands and examples?

I used this (poor) code to make the list of commands

on http://drupal.org/node/477684 with 
function drush_show_help_dl($what="description") {
  $cs = drush_get_commands();
  ksort($cs);
  drush_print('<dl>');
  foreach ($cs as $c => $v) {
    $a = array_flip($v['aliases']);
    unset($a[$c]);
    drush_print('<dt>' . $c . ' (' . implode(',', array_keys($a)) . ')</dt><dd>' . $v['description'] . '</dd>');
  }
  drush_print('<dl>');
  return;
}

The same way we could extract the examples on that page too.

Trouble with the code above is that the aliases are repeated. How could the code get improved? I'm not sure why function drush_show_help($commands) is way more complex or the other way around :p

Thanks

Comments

greg.1.anderson’s picture

greg.1.anderson commented

Maybe what we need is an --html-output flag for drush help...

clemens.tolboom’s picture

clemens.tolboom
Primary language Dutch
Location Groningen, 🇳🇱/🇪🇺
commented

That flag would be great to have for the list of commands. But how can we extract all examples at once?

Maybe a drush --html-output --verbose help could to the job?

moshe weitzman’s picture

moshe weitzman commented

drush --html-output --verbose help sounds good to me.

this can be a slippery slope though. Pretty soon, people want to add internal and external hyperlinks and images and you've recreated doxygen.

moshe weitzman’s picture

moshe weitzman commented
Title: Improving documentation through drush » HTML documentation through drush
Assigned: Unassigned » moshe weitzman

I went ahead and implemented a --html option and committed to HEAD. You can see example output at http://d7cx.com/drush (will soon move to drush.ws). From the commit msg ...

drush help can now output an HTML page documenting all the available commands. Great for dev teams or anytime you need an URL to send around.

There is one remaining problem and I could use help fixing it. The calls to drush_show_help() are duplicated in the command output. The whole HTML page is prefixed by the detailed command listing. Its pretty ugly. I am using ob_start() in an attempt to avoid this but not succeeding. Leaving issue open until this bug is resolved.

moshe weitzman’s picture

moshe weitzman commented
Status: Active » Fixed

that duplication was fixed days ago.

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.