Chris@0: <?php
Chris@0: /**
Chris@0:  * A doc generator that outputs documentation in Markdown format.
Chris@0:  *
Chris@0:  * PHP version 5
Chris@0:  *
Chris@0:  * @category  PHP
Chris@0:  * @package   PHP_CodeSniffer
Chris@0:  * @author    Stefano Kowalke <blueduck@gmx.net>
Chris@0:  * @copyright 2014 Arroba IT
Chris@0:  * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
Chris@0:  * @link      http://pear.php.net/package/PHP_CodeSniffer
Chris@0:  */
Chris@0: 
Chris@0: if (class_exists('PHP_CodeSniffer_DocGenerators_Generator', true) === false) {
Chris@0:     throw new PHP_CodeSniffer_Exception('Class PHP_CodeSniffer_DocGenerators_Generator not found');
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * A doc generator that outputs documentation in Markdown format.
Chris@0:  *
Chris@0:  * @category  PHP
Chris@0:  * @package   PHP_CodeSniffer
Chris@0:  * @author    Stefano Kowalke <blueduck@gmx.net>
Chris@0:  * @copyright 2014 Arroba IT
Chris@0:  * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
Chris@0:  * @version   Release: @package_version@
Chris@0:  * @link      http://pear.php.net/package/PHP_CodeSniffer
Chris@0:  */
Chris@0: class PHP_CodeSniffer_DocGenerators_Markdown extends PHP_CodeSniffer_DocGenerators_Generator
Chris@0: {
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Generates the documentation for a standard.
Chris@0:      *
Chris@0:      * @return void
Chris@0:      * @see    processSniff()
Chris@0:      */
Chris@0:     public function generate()
Chris@0:     {
Chris@0:         ob_start();
Chris@0:         $this->printHeader();
Chris@0: 
Chris@0:         $standardFiles = $this->getStandardFiles();
Chris@0: 
Chris@0:         foreach ($standardFiles as $standard) {
Chris@0:             $doc = new DOMDocument();
Chris@0:             $doc->load($standard);
Chris@0:             $documentation = $doc->getElementsByTagName('documentation')->item(0);
Chris@0:             $this->processSniff($documentation);
Chris@0:         }
Chris@0: 
Chris@0:         $this->printFooter();
Chris@0:         $content = ob_get_contents();
Chris@0:         ob_end_clean();
Chris@0: 
Chris@0:         echo $content;
Chris@0: 
Chris@0:     }//end generate()
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Print the markdown header.
Chris@0:      *
Chris@0:      * @return void
Chris@0:      */
Chris@0:     protected function printHeader()
Chris@0:     {
Chris@0:         $standard = $this->getStandard();
Chris@0: 
Chris@0:         echo "# $standard Coding Standard".PHP_EOL;
Chris@0: 
Chris@0:     }//end printHeader()
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Print the markdown footer.
Chris@0:      *
Chris@0:      * @return void
Chris@0:      */
Chris@0:     protected function printFooter()
Chris@0:     {
Chris@0:         // Turn off errors so we don't get timezone warnings if people
Chris@0:         // don't have their timezone set.
Chris@0:         error_reporting(0);
Chris@0:         echo 'Documentation generated on '.date('r');
Chris@0:         echo ' by [PHP_CodeSniffer '.PHP_CodeSniffer::VERSION.'](https://github.com/squizlabs/PHP_CodeSniffer)';
Chris@0: 
Chris@0:     }//end printFooter()
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Process the documentation for a single sniff.
Chris@0:      *
Chris@0:      * @param DOMNode $doc The DOMNode object for the sniff.
Chris@0:      *                     It represents the "documentation" tag in the XML
Chris@0:      *                     standard file.
Chris@0:      *
Chris@0:      * @return void
Chris@0:      */
Chris@0:     protected function processSniff(DOMNode $doc)
Chris@0:     {
Chris@0:         $title = $this->getTitle($doc);
Chris@0:         echo "## $title".PHP_EOL;
Chris@0: 
Chris@0:         foreach ($doc->childNodes as $node) {
Chris@0:             if ($node->nodeName === 'standard') {
Chris@0:                 $this->printTextBlock($node);
Chris@0:             } else if ($node->nodeName === 'code_comparison') {
Chris@0:                 $this->printCodeComparisonBlock($node);
Chris@0:             }
Chris@0:         }
Chris@0: 
Chris@0:     }//end processSniff()
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Print a text block found in a standard.
Chris@0:      *
Chris@0:      * @param DOMNode $node The DOMNode object for the text block.
Chris@0:      *
Chris@0:      * @return void
Chris@0:      */
Chris@0:     protected function printTextBlock(DOMNode $node)
Chris@0:     {
Chris@0:         $content = trim($node->nodeValue);
Chris@0:         $content = htmlspecialchars($content);
Chris@0: 
Chris@0:         $content = str_replace('&lt;em&gt;', '*', $content);
Chris@0:         $content = str_replace('&lt;/em&gt;', '*', $content);
Chris@0: 
Chris@0:         echo $content.PHP_EOL;
Chris@0: 
Chris@0:     }//end printTextBlock()
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Print a code comparison block found in a standard.
Chris@0:      *
Chris@0:      * @param DOMNode $node The DOMNode object for the code comparison block.
Chris@0:      *
Chris@0:      * @return void
Chris@0:      */
Chris@0:     protected function printCodeComparisonBlock(DOMNode $node)
Chris@0:     {
Chris@0:         $codeBlocks = $node->getElementsByTagName('code');
Chris@0: 
Chris@0:         $firstTitle = $codeBlocks->item(0)->getAttribute('title');
Chris@0:         $first      = trim($codeBlocks->item(0)->nodeValue);
Chris@0:         $first      = str_replace("\n", "\n    ", $first);
Chris@0:         $first      = str_replace('<em>', '', $first);
Chris@0:         $first      = str_replace('</em>', '', $first);
Chris@0: 
Chris@0:         $secondTitle = $codeBlocks->item(1)->getAttribute('title');
Chris@0:         $second      = trim($codeBlocks->item(1)->nodeValue);
Chris@0:         $second      = str_replace("\n", "\n    ", $second);
Chris@0:         $second      = str_replace('<em>', '', $second);
Chris@0:         $second      = str_replace('</em>', '', $second);
Chris@0: 
Chris@0:         echo '  <table>'.PHP_EOL;
Chris@0:         echo '   <tr>'.PHP_EOL;
Chris@0:         echo "    <th>$firstTitle</th>".PHP_EOL;
Chris@0:         echo "    <th>$secondTitle</th>".PHP_EOL;
Chris@0:         echo '   </tr>'.PHP_EOL;
Chris@0:         echo '   <tr>'.PHP_EOL;
Chris@0:         echo '<td>'.PHP_EOL.PHP_EOL;
Chris@0:         echo "    $first".PHP_EOL.PHP_EOL;
Chris@0:         echo '</td>'.PHP_EOL;
Chris@0:         echo '<td>'.PHP_EOL.PHP_EOL;
Chris@0:         echo "    $second".PHP_EOL.PHP_EOL;
Chris@0:         echo '</td>'.PHP_EOL;
Chris@0:         echo '   </tr>'.PHP_EOL;
Chris@0:         echo '  </table>'.PHP_EOL;
Chris@0: 
Chris@0:     }//end printCodeComparisonBlock()
Chris@0: 
Chris@0: 
Chris@0: }//end class