Markdown-Dokumentation für Backends

Entwickler- und Anwenderdokumentationen einer Webanwendung oder API entstehen eigentlich immer parallel beim Programmieren. Um dafür kein zusätzliches Programm nutzen zu müssen, schreibe ich gerne Markdown-Files direkt mit dem gerade verwendeten Editor/ IDE.
Markdown deshalb, weil man die Dokumente, zum Beispiel mit Byword, in alle möglichen Formate konvertieren kann.

Den konvertierten HTML-Code kann man dann beispielsweise leicht in ein Backend oder die API-Dokumentation kopieren – oder aber man baut sich ein kleines PHP-Skript, was das übernimmt :–)

Das nachfolgende Skript ist ein Auszug aus einem symfony-Projekt, lässt sich aber leicht übertragen. Für das Parsen des Markdown wird php-markdown von John Gruber eingebunden.

<?php
/**
 * Install PSR-0-compatible class autoloader
 */
spl_autoload_register(function($class) {
  require_once (sfConfig::get('sf_lib_dir') . '/vendor/Markdown.php');
});
use \Michelf\Markdown;

class docActions extends sfActions
{

  public function executeUser(sfWebRequest $request)
  {
    $this->docs = $this->getDocs(sfConfig::get('app_docs_user'));
  }

  protected function getDocs($dir)
  {
    $docs = array();
    if ($dir_handle = opendir($dir)) {
      while (false !== ($file = readdir($dir_handle))) {
        $info = new SplFileInfo($file);
        if ($info->getExtension() == 'md' || $info->getExtension() == 'markdown') {
          $file_handle = fopen($dir . $file, 'r');
          $docs[] = array(
            'file' => $info->getBasename(),
            'anker' => Doctrine_Inflector::unaccent($info->getBasename('.' . $info->getExtension())),
            'title' => trim(fgets($file_handle)),
            'last_modified' => date("d.m.Y", filemtime($dir . $file)),
            'content' => Markdown::defaultTransform(file_get_contents($dir . $file)),
          );
          fclose($file_handle);
        }
      }
      closedir($dir_handle);
    }
    return $docs;
  }
}

Wie am HTML auffallen könnte, benutze ich im View Twitter Bootstrap mit der dem affix plugin.

<div class="row">
    <div class="span4 aside">
        <ul class="nav nav-tabs nav-list nav-stacked" data-spy="affix">
            <li class="active">
                <a href="#intro">Einleitung</a>
            </li>
            <?php foreach ($docs as $doc): ?>
                <li>
                    <a href="#<?php echo $doc['anker'] ?>">
                        <?php echo $doc['title'] ?><br>
                        <small>
                          <?php echo $doc['last_modified'] ?>
                        </small>
                    </a>
                </li>
            <?php endforeach ?>
        </ul>
    </div>
    <div class="span8">
        <section id="intro">
            <h1>Anwenderdokumentation</h1>
        </section>
        <?php foreach ($docs as $doc): ?>
            <section id="<?php echo $doc['anker'] ?>">
                <?php echo $doc['content'] ?>
            </section>
        <?php endforeach ?>
    </div>
</div>

Schreibe einen Kommentar

Pflichtfelder sind mit * markiert.


18 − = 9