Updates for the next Doctum version

composer.json

@@ -12,7 +12,7 @@
         "php": "^7",
         "gitonomy/gitlib": "~1.0",
         "symfony/console": "^3.3",
-        "code-lts/doctum": "^5.2.0"
+        "code-lts/doctum": "^5.3.1"
     },
     "bin": [
         "bin/docs"

conf/doctum.php

@@ -8,7 +8,7 @@
 use SilverStripe\ApiDocs\Data\Config;
 use SilverStripe\ApiDocs\Inspections\RecipeFinder;
 use SilverStripe\ApiDocs\Inspections\RecipeVersionCollection;
-use SilverStripe\ApiDocs\Twig\NavigationExtension;
+use SilverStripe\ApiDocs\RemoteRepository\SilverStripeRemoteRepository;
 
 // Get config
 $config = Config::getConfig();
@@ -37,6 +37,8 @@
     'versions' => $versions,
     'build_dir' => Config::configPath($config['paths']['www']) . '/%version%',
     'cache_dir' => Config::configPath($config['paths']['cache']) . '/%version%',
+    'source_dir' => $versions->getPackagePath(''),// Root of all the packages
+    'remote_repository' => new SilverStripeRemoteRepository('', $versions->getPackagePath('') . '/'),
     'template_dirs' => [ __DIR__ .'/themes' ],
 ]);
 
@@ -57,15 +59,6 @@
     return new \SilverStripe\ApiDocs\Renderer\SilverStripeRenderer($sc['twig'], $sc['themes'], $sc['tree'], $sc['indexer']);
 };
 
-// Override twig
-/** @var Twig_Environment $twig */
-$twig = $doctum['twig'];
-unset($doctum['twig']);
-$doctum['twig'] = function () use ($twig) {
-    $twig->addExtension(new NavigationExtension());
-    return $twig;
-};
-
 // Override json store
 $store = $doctum['store'];
 unset($doctum['store']);

src/Inspections/RecipeVersionCollection.php

@@ -137,9 +137,9 @@ protected function switchVersion(Version $version)
      * @param string $package
      * @return string
      */
-    public function getPackagePath($package)
+    public function getPackagePath(string $package): string
     {
-        return Config::configPath($this->config['paths']['packages'] . '/' . $package);
+        return realpath(Config::configPath($this->config['paths']['packages'] . '/' . $package));
     }
 
     /**

src/Parser/SilverStripeNodeVisitor.php

@@ -2,72 +2,26 @@
 
 namespace SilverStripe\ApiDocs\Parser;
 
-use PhpParser\Node\Stmt\Class_ as ClassNode;
 use Doctum\Parser\NodeVisitor;
 use PhpParser\Node\Stmt\ClassLike as ClassLikeNode;
 use PhpParser\Node\Stmt\Property as PropertyNode;
-use Doctum\Reflection\PropertyReflection;
 use SilverStripe\ApiDocs\Reflection\SilverStripeClassReflection;
 
 class SilverStripeNodeVisitor extends NodeVisitor
 {
     protected function addClassOrInterface(ClassLikeNode $node)
     {
         $class = new SilverStripeClassReflection((string) $node->namespacedName, $node->getLine());
-        if ($node instanceof ClassNode) {
-            $class->setModifiers($node->flags);
-        }
-        $class->setNamespace($this->context->getNamespace());
-        $class->setAliases($this->context->getAliases());
-        $class->setHash($this->context->getHash());
-        $class->setFile($this->context->getFile());
-
-        $comment = $this->context->getDocBlockParser()->parse($node->getDocComment(), $this->context, $class);
-        $class->setDocComment($node->getDocComment());
-        $class->setShortDesc($comment->getShortDesc());
-        $class->setLongDesc($comment->getLongDesc());
-        if ($errors = $comment->getErrors()) {
-            $class->setErrors($errors);
-        } else {
-            $class->setTags($comment->getOtherTags());
-        }
-
-        if ($this->context->getFilter()->acceptClass($class)) {
-            if ($errors) {
-                $this->context->addErrors((string) $class, $node->getLine(), $errors);
-            }
-            $this->context->enterClass($class);
-        }
-
-        return $class;
+        return $this->addClassOrInterfaceForReflection($class, $node);
     }
 
     protected function addProperty(PropertyNode $node)
     {
         foreach ($node->props as $prop) {
-            $property = new PropertyReflection($prop->name, $prop->getLine());
-            $property->setModifiers($node->flags);
-
-            $property->setDefault($prop->default);
-
-            $comment = $this->context->getDocBlockParser()->parse($node->getDocComment(), $this->context, $property);
-            $property->setDocComment($node->getDocComment());
-            $property->setShortDesc($comment->getShortDesc());
-            $property->setLongDesc($comment->getLongDesc());
-            if ($errors = $comment->getErrors()) {
-                $property->setErrors($errors);
-            } else {
-                $this->addTagFromCommentToMethod('var', $comment, $property, $errors);
-
-                $property->setTags($comment->getOtherTags());
-            }
+            [$property, $errors] = $this->getPropertyReflectionFromParserProperty($node, $prop);
 
             if ($this->context->getFilter()->acceptProperty($property)) {
-                if ($property->getTags('config')) {
-                    $this->context->getClass()->addConfig($property);
-                } else {
-                    $this->context->getClass()->addProperty($property);
-                }
+                $this->context->getClass()->addProperty($property);
 
                 if ($errors) {
                     $this->context->addErrors((string) $property, $prop->getLine(), $errors);

src/Reflection/SilverStripeClassReflection.php

@@ -7,24 +7,17 @@
 
 class SilverStripeClassReflection extends ClassReflection
 {
-    const CATEGORY_CONFIG = 4;
-
-    private static $categoryName = [
-        1 => 'class',
-        2 => 'interface',
-        3 => 'trait',
-        4 => 'config',
-    ];
 
+    /** @var array<string,PropertyReflection> */
     protected $configs = [];
 
-    public function addConfig(PropertyReflection $property)
+    public function addConfig(PropertyReflection $property): void
     {
         $this->configs[$property->getName()] = $property;
         $property->setClass($this);
     }
 
-    public function getConfigs()
+    public function getConfigs(): array
     {
         return $this->configs;
     }

src/RemoteRepository/SilverStripeRemoteRepository.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace SilverStripe\ApiDocs\RemoteRepository;
+
+use Doctum\RemoteRepository\AbstractRemoteRepository;
+use SilverStripe\ApiDocs\Data\Config;
+
+class SilverStripeRemoteRepository extends AbstractRemoteRepository
+{
+
+    public function getFileUrl($projectVersion, $relativePath, $line)
+    {
+        // $this->localPath is the root path to packages
+        // Example: /mnt/Dev/@code-lts/@doctum-fork/api.silverstripe.org/data/packages/
+        // $this->name is empty, and not used
+        // $relativePath for the current file
+        // Example "silverstripe/admin/code/AdminRootController.php"
+        $pathParts = explode('/', $relativePath, 3);
+        // Example: [silverstripe, admin, code/AdminRootController.php]
+        $this->name = $pathParts[0] . '/' . $pathParts[1];
+
+        $packageConfig = Config::getConfig()['packages'][$this->name];
+        $rootPath = $packageConfig['repository'];
+        if (substr($rootPath, -4) === '.git') {
+            $rootPath = substr($rootPath, 0, -4);
+        }
+        if (isset($packageConfig['versionmap'])) {
+            $versionMaps = Config::getConfig()['versionmaps'];
+            $projectVersion = $versionMaps[$packageConfig['versionmap']][(string) $projectVersion] ?? $projectVersion;
+        }
+        $url = $rootPath . '/blob/' . $this->buildProjectPath($projectVersion, $pathParts[2]);
+
+        if (null !== $line) {
+            $url .= '#L' . (int) $line;
+        }
+
+        return $url;
+    }
+}

src/Renderer/SilverStripeRenderer.php

@@ -2,7 +2,6 @@
 
 namespace SilverStripe\ApiDocs\Renderer;
 
-use Doctum\Message;
 use Doctum\Project;
 use Doctum\Renderer\Renderer;
 use SilverStripe\ApiDocs\Reflection\SilverStripeClassReflection;
@@ -12,85 +11,23 @@ class SilverStripeRenderer extends Renderer
     protected function renderClassTemplates(array $classes, Project $project, $callback = null)
     {
         foreach ($classes as $class) {
-            if (null !== $callback) {
-                call_user_func(
-                    $callback,
-                    Message::RENDER_PROGRESS,
-                    ['Class', $class->getName(), $this->step, $this->steps]
-                );
-            }
-
-            $properties = $class->getProperties($project->getConfig('include_parent_data'));
+            $variables = $this->getVariablesFromClassReflection($class, $project, $callback);
 
-            $sortProperties = $project->getConfig('sort_class_properties');
-            if ($sortProperties) {
-                if (is_callable($sortProperties)) {
-                    uksort($properties, $sortProperties);
-                } else {
-                    ksort($properties);
-                }
-            }
+            $configs = [];
 
             if ($class instanceof SilverStripeClassReflection) {
                 $configs = $class->getConfigs($project->getConfig('include_parent_data'));
+                $sortProperties = $project->getConfig('sort_class_properties');
                 if ($sortProperties) {
                     if (is_callable($sortProperties)) {
                         uksort($configs, $sortProperties);
                     } else {
                         ksort($properties);
                     }
                 }
-            } else {
-                $configs = array();
-            }
-
-            $methods = $class->getMethods($project->getConfig('include_parent_data'));
-
-            $sortMethods = $project->getConfig('sort_class_methods');
-            if ($sortMethods) {
-                if (is_callable($sortMethods)) {
-                    uksort($methods, $sortMethods);
-                } else {
-                    ksort($methods);
-                }
-            }
-
-            $constants = $class->getConstants($project->getConfig('include_parent_data'));
-
-            $sortConstants = $project->getConfig('sort_class_constants');
-            if ($sortConstants) {
-                if (is_callable($sortConstants)) {
-                    uksort($constants, $sortConstants);
-                } else {
-                    ksort($constants);
-                }
-            }
-
-            $traits = $class->getTraits($project->getConfig('include_parent_data'));
-
-            $sortTraits = $project->getConfig('sort_class_traits');
-            if ($sortTraits) {
-                if (is_callable($sortTraits)) {
-                    uksort($traits, $sortTraits);
-                } else {
-                    ksort($traits);
-                }
-            }
-
-            $sortInterfaces = $project->getConfig('sort_class_interfaces');
-            if ($sortInterfaces) {
-                $class->sortInterfaces($sortInterfaces);
             }
 
-            $variables = [
-                'class' => $class,
-                'properties' => $properties,
-                'configs' => $configs,
-                'methods' => $methods,
-                'constants' => $constants,
-                'traits' => $traits,
-                'tree' => $this->getTree($project),
-            ];
+            $variables['configs'] = $configs;
 
             foreach ($this->theme->getTemplates('class') as $template => $target) {
                 $this->save(
@@ -102,14 +39,4 @@ protected function renderClassTemplates(array $classes, Project $project, $callb
             }
         }
     }
-
-    private function getTree(Project $project)
-    {
-        $key = $project->getBuildDir();
-        if (!isset($this->cachedTree[$key])) {
-            $this->cachedTree[$key] = $this->tree->getTree($project);
-        }
-
-        return $this->cachedTree[$key];
-    }
 }