Merge pull request #2836 from phpDocumentor/guides-render-code-blocks

Guides: Render code blocks
phpDocumentor · Feb 28, 2021 · 7fb97b8 · 7fb97b8
2 parents ade4858 + 0125289
commit 7fb97b8
Show file tree

Hide file tree

Showing 15 changed files with 93 additions and 242 deletions.
diff --git a/composer.json b/composer.json
@@ -53,7 +53,6 @@
         "phpdocumentor/type-resolver": "^1.0",
         "psr/cache": "^1.0",
         "psr/log": "^1.1",
-        "scrivo/highlight.php": "^9.17",
         "symfony/cache": "^5.0",
         "symfony/config": "^5.0",
         "symfony/console": "^5.0",

diff --git a/composer.lock b/composer.lock
diff --git a/data/templates/default/css/normalize.css.twig b/data/templates/default/css/normalize.css.twig
@@ -230,7 +230,7 @@ code,
 kbd,
 pre,
 samp {
-    font-family: monospace, monospace;
+    font-family: var(--font-monospace);
     font-size: 1em;
 }
 

diff --git a/data/templates/default/css/variables.css.twig b/data/templates/default/css/variables.css.twig
@@ -2,6 +2,7 @@
     /* Typography */
     --font-primary: 'Source Sans Pro', Helvetica, Arial, sans-serif;
     --font-secondary: 'Source Sans Pro', Helvetica, Arial, sans-serif;
+    --font-monospace: 'Source Code Pro', monospace;
     --line-height--primary: 1.6;
     --letter-spacing--primary: .05rem;
     --text-base-size: 1em;
@@ -22,12 +23,13 @@
     --primary-color: hsl(96, 57%, 60%);
     --primary-color-darken: hsl(96, 57%, 40%);
     --primary-color-darker: hsl(96, 57%, 20%);
+    --primary-color-darkest: hsl(96, 57%, 10%);
     --primary-color-lighten: hsl(96, 57%, 80%);
     --primary-color-lighter: hsl(96, 57%, 99%);
     --dark-gray: #d1d1d1;
     --light-gray: #f0f0f0;
 
-    --text-color: #4b3b40;
+    --text-color: var(--primary-color-darkest);
 
     --header-height: var(--spacing-xxxxl);
     --header-bg-color: var(--primary-color);

diff --git a/data/templates/default/guides/code.html.twig b/data/templates/default/guides/code.html.twig
@@ -1 +1 @@
-<pre class="{% if codeNode.classes %}{{ codeNode.classesString }}{% endif %} phpdocumentor-code -dark"><code class="{{ codeNode.language }}">{{ codeNode.value }}</code></pre>
+<pre><code class="language-{{ language }} {{ startingLineNumber ? 'line-numbers' }}" {{ startingLineNumber ? 'data-start=' ~ startingLineNumber }}>{{ code }}</code></pre>
diff --git a/data/templates/default/layout.html.twig b/data/templates/default/layout.html.twig
@@ -9,9 +9,13 @@
     <link rel="stylesheet" href="css/normalize.css">
     <link rel="stylesheet" href="css/base.css">
     {% block stylesheets %}
+        <link rel="preconnect" href="https://fonts.gstatic.com">
         <link href="https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;600;700&display=swap" rel="stylesheet">
+        <link href="https://fonts.googleapis.com/css2?family=Source+Code+Pro:wght@400;600;700&display=swap" rel="stylesheet">
         <link rel="stylesheet" href="css/template.css">
         <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.0/css/all.min.css" integrity="sha256-ybRkN9dBjhcS2qrW1z+hfCxq+1aBdwyQM5wlQoQVt/0=" crossorigin="anonymous" />
+        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/themes/prism-okaidia.css">
+        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/plugins/line-numbers/prism-line-numbers.css">
     {% endblock %}
     {% block javascripts %}
         <script src="https://cdn.jsdelivr.net/npm/fuse.js@3.4.6"></script>
@@ -38,5 +42,8 @@
     <script>
         cssVars({});
     </script>
+    <script src="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/prism.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/plugins/autoloader/prism-autoloader.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/plugins/line-numbers/prism-line-numbers.min.js"></script>
 </body>
 </html>
diff --git a/data/templates/default/objects/code.css.twig b/data/templates/default/objects/code.css.twig
@@ -3,6 +3,7 @@
 }
 
 .phpdocumentor-code {
+    font-family: var(--font-monospace);
     background: var(--code-background-color);
     border: 1px solid var(--code-border-color);
     border-radius: var(--border-radius-base-size);
@@ -13,12 +14,9 @@
 }
 
 .phpdocumentor-code.-dark {
-    background: var(--text-color);
-    color: var(--primary-color-lighter);
-    padding: .5rem 1rem;
-    border-radius: .25rem;
+    background: var(--primary-color-darkest);
+    color: var(--light-gray);
     box-shadow: 0 2px 3px var(--dark-gray);
-    font-size: 0.8rem;
 }
 
 pre > .phpdocumentor-code {

diff --git a/docs/getting-started/your-first-set-of-documentation.rst b/docs/getting-started/your-first-set-of-documentation.rst
@@ -65,7 +65,7 @@ For example:
 
    The following DocBlock is a File-level DocBlock:
 
-   .. code-block:: php
+   .. code:: php
 
       <?php
       /**
@@ -172,7 +172,9 @@ After you have :doc:`installed<installing>` phpDocumentor you can use the ``phpd
 your documentation.
 
 Throughout this documentation we expect that the ``phpdoc`` command is available; thus whenever we ask you
-to run a command, it will be in the following form::
+to run a command, it will be in the following form
+
+.. code-block:: shell-session
 
     $ phpdoc
 
@@ -181,19 +183,25 @@ to run a command, it will be in the following form::
     When you have installed a version via composer or manually you should invoke the ``phpdoc`` script in
     the ``bin`` folder of your phpDocumentor installation.
 
-    Under Linux / MacOSX that would be::
+    Under Linux / MacOSX that would be
+
+    .. code-block:: shell-session
 
         $ [PHPDOC_FOLDER]/bin/phpdoc
 
-    And under Windows that would be::
+    And under Windows that would be
+
+    .. code-block:: shell-session
 
         $ [PHPDOC_FOLDER]\bin\phpdoc.bat
 
 The basic usage of phpDocumentor is to provide an input location using the command line options
 (``-d`` for a directory, ``-f`` for a file) and tell it to output your documentation to a folder of your
 liking (``-t``).
 
-For example::
+For example:
+
+.. code-block:: shell-session
 
     $ phpdoc -d ./src -t ./docs/api
 

diff --git a/src/Guides/Nodes/CodeNode.php b/src/Guides/Nodes/CodeNode.php
@@ -22,7 +22,10 @@ class CodeNode extends Node
     protected $raw = false;
 
     /** @var string|null */
-    protected $language = null;
+    protected $language;
+
+    /** @var int|null The line number to start counting from and display, or null to hide line numbers */
+    private $startingLineNumber;
 
     /**
      * @param string[] $lines
@@ -47,6 +50,16 @@ public function getLanguage() : ?string
         return $this->language;
     }
 
+    public function setStartingLineNumber(?int $lineNumber) : void
+    {
+        $this->startingLineNumber = $lineNumber;
+    }
+
+    public function getStartingLineNumber() : ?int
+    {
+        return $this->startingLineNumber;
+    }
+
     public function setRaw(bool $raw) : void
     {
         $this->raw = $raw;

diff --git a/src/Guides/Renderers/Html/CodeNodeRenderer.php b/src/Guides/Renderers/Html/CodeNodeRenderer.php
@@ -13,42 +13,12 @@
 
 namespace phpDocumentor\Guides\Renderers\Html;
 
-use Highlight\Highlighter;
 use phpDocumentor\Guides\Nodes\CodeNode;
 use phpDocumentor\Guides\Renderer;
 use phpDocumentor\Guides\Renderers\NodeRenderer;
-use function array_keys;
-use function array_merge;
-use function array_reverse;
-use function count;
-use function implode;
-use function in_array;
-use function preg_split;
-use function rtrim;
-use function str_pad;
-use function trim;
-use const STR_PAD_LEFT;
 
 class CodeNodeRenderer implements NodeRenderer
 {
-//    private static $isHighlighterConfigured = false;
-
-    private const LANGUAGES_MAPPING = [
-        'html+jinja' => 'twig',
-        'html+twig' => 'twig',
-        'jinja' => 'twig',
-        'html+php' => 'html',
-        'xml+php' => 'xml',
-        'php-annotations' => 'php',
-        'terminal' => 'bash',
-        'rst' => 'markdown',
-        'php-standalone' => 'php',
-        'php-symfony' => 'php',
-        'varnish4' => 'c',
-        'varnish3' => 'c',
-        'vcl' => 'c',
-    ];
-
     /** @var CodeNode */
     private $codeNode;
 
@@ -63,81 +33,19 @@ public function __construct(CodeNode $codeNode)
 
     public function render() : string
     {
-        $this->configureHighlighter();
-
         $value = $this->codeNode->getValue();
 
         if ($this->codeNode->isRaw()) {
             return $value;
         }
 
-        $lines = $this->getLines($value);
-        $code = implode("\n", $lines);
-
-        $lineNumbers = '';
-        for ($i = 1, $nbLines = count($lines); $i <= $nbLines; ++$i) {
-            $lineNumbers .= str_pad((string) $i, 2, ' ', STR_PAD_LEFT) . "\n";
-        }
-
-        $language = $this->codeNode->getLanguage() ?? 'php';
-
-        if ($language !== 'text' && $language !== '') {
-            $highLighter = new Highlighter();
-            $code = $highLighter->highlight(self::LANGUAGES_MAPPING[$language] ?? $language, $code)->value;
-        }
-
         return $this->renderer->render(
             'code.html.twig',
             [
-                'codeNode' => $this->codeNode,
-                'language' => $language,
-                'languageMapping' => self::LANGUAGES_MAPPING[$language] ?? $language,
-                'code' => $code,
-                'lineNumbers' => rtrim($lineNumbers),
+                'code' => $this->codeNode->getValue(),
+                'language' => $this->codeNode->getLanguage(),
+                'startingLineNumber' => $this->codeNode->getStartingLineNumber(),
             ]
         );
     }
-
-    public static function isLanguageSupported(string $lang) : bool
-    {
-        $highlighter = new Highlighter();
-        $supportedLanguages = array_merge(
-            array_keys(self::LANGUAGES_MAPPING),
-            $highlighter->listLanguages(true),
-            // not highlighted, but valid
-            ['text']
-        );
-
-        return in_array($lang, $supportedLanguages, true);
-    }
-
-    /**
-     * @return array<string>
-     */
-    private function getLines(string $code) : array
-    {
-        $lines = preg_split('/\r\n|\r|\n/', $code);
-        $reversedLines = array_reverse($lines);
-
-        // trim empty lines at the end of the code
-        foreach ($reversedLines as $key => $line) {
-            if (trim($line) !== '') {
-                break;
-            }
-
-            unset($reversedLines[$key]);
-        }
-
-        return array_reverse($reversedLines);
-    }
-
-    private function configureHighlighter() : void
-    {
-//        if (!self::$isHighlighterConfigured) {
-//            Highlighter::registerLanguage('php', 'guides/highlight.php/php.json', true);
-//            Highlighter::registerLanguage('twig', 'guides/highlight.php/twig.json', true);
-//        }
-//
-//        self::$isHighlighterConfigured = true;
-    }
 }