Properly fixing next/prev/parents in the JSON files

This was researched specifically using Sphinx behavior

Author: weaverryan

src/BuildResult.php

@@ -16,13 +16,13 @@
 class BuildResult
 {
     private $errors;
-    private $metas;
+    private $builder;
     private $jsonResults = [];
 
-    public function __construct(array $errors, Metas $metas)
+    public function __construct(array $errors, Builder $builder)
     {
         $this->errors = $errors;
-        $this->metas = $metas;
+        $this->builder = $builder;
     }
 
     public function appendError(string $errorMessage): void
@@ -47,7 +47,19 @@ public function getErrors(): array
 
     public function getMetas(): Metas
     {
-        return $this->metas;
+        return $this->builder->getMetas();
+    }
+
+    /**
+     * Returns the "master document": the first file whose toctree is parsed.
+     *
+     * Unless customized, this is "index" (i.e. file index.rst).
+     *
+     * @return string
+     */
+    public function getMasterDocumentFilename(): string
+    {
+        return $this->builder->getIndexName();
     }
 
     /**

src/DocBuilder.php

@@ -27,7 +27,7 @@ public function build(BuildConfig $config): BuildResult
 
         $buildResult = new BuildResult(
             $builder->getErrorManager()->getErrors(),
-            $builder->getMetas()
+            $builder
         );
 
         $missingFilesChecker = new MissingFilesChecker($config);
@@ -47,7 +47,7 @@ public function build(BuildConfig $config): BuildResult
             $htmlForPdfGenerator->generateHtmlForPdf();
         } else {
             $jsonGenerator = new JsonGenerator($metas, $config);
-            $buildResult->setJsonResults($jsonGenerator->generateJson());
+            $buildResult->setJsonResults($jsonGenerator->generateJson($builder->getIndexName()));
         }
 
         return $buildResult;

src/Generator/JsonGenerator.php

@@ -40,31 +40,46 @@ public function __construct(Metas $metas, BuildConfig $buildConfig)
     /**
      * Returns an array of each JSON file string, keyed by the input filename
      *
+     * @param string $masterDocument The file whose toctree should be read first
      * @return string[]
      */
-    public function generateJson(): array
+    public function generateJson(string $masterDocument = 'index'): array
     {
         $fs = new Filesystem();
 
         $progressBar = new ProgressBar($this->output ?: new NullOutput());
         $progressBar->setMaxSteps(\count($this->metas->getAll()));
 
+        $walkedFiles = [];
+        $tocTreeHierarchy = $this->walkTocTreeAndReturnHierarchy(
+            $masterDocument,
+            $walkedFiles
+        );
+        // for purposes of prev/next/parents, the "master document"
+        // behaves as if it's the first item in the toctree
+        $tocTreeHierarchy = [$masterDocument => []] + $tocTreeHierarchy;
+        $flattenedTocTree = $this->flattenTocTree($tocTreeHierarchy);
+
         $fJsonFiles = [];
         foreach ($this->metas->getAll() as $filename => $metaEntry) {
             $parserFilename = $filename;
             $jsonFilename = $this->buildConfig->getOutputDir().'/'.$filename.'.fjson';
 
             $crawler = new Crawler(file_get_contents($this->buildConfig->getOutputDir().'/'.$filename.'.html'));
 
+            $next = $this->determineNext($parserFilename, $flattenedTocTree, $masterDocument);
+            $prev = $this->determinePrev($parserFilename, $flattenedTocTree);
             $data = [
                 'title' => $metaEntry->getTitle(),
+                'parents' => $this->determineParents($parserFilename, $tocTreeHierarchy) ?: [],
                 'current_page_name' => $parserFilename,
                 'toc' => $this->generateToc($metaEntry, current($metaEntry->getTitles())[1]),
-                'next' => $this->guessNext($parserFilename),
-                'prev' => $this->guessPrev($parserFilename),
+                'next' => $next,
+                'prev' => $prev,
                 'rellinks' => [
-                    $this->guessNext($parserFilename),
-                    $this->guessPrev($parserFilename),
+                    // probably these shouldn't be straight copies of next/prev
+                    $next,
+                    $prev,
                 ],
                 'body' => $crawler->filter('body')->html(),
             ];
@@ -109,128 +124,162 @@ private function generateToc(MetaEntry $metaEntry, ?array $titles): array
         return $tocTree;
     }
 
-    private function guessNext(string $parserFilename): ?array
+    private function determineNext(string $parserFilename, array $flattenedTocTree): ?array
     {
-        $meta = $this->getMetaEntry($parserFilename, true);
-
-        $parentFile = $meta->getParent();
+        $foundCurrentFile = false;
+        $nextFileName = null;
 
-        // if current file is an index, next is the first chapter
-        if ('index' === $parentFile && 1 === \count($tocs = $meta->getTocs()) && \count($tocs[0]) > 0) {
-            $firstChapterMeta = $this->getMetaEntry($tocs[0][0]);
+        foreach ($flattenedTocTree as $filename) {
+            if ($foundCurrentFile) {
+                $nextFileName = $filename;
 
-            if (null === $firstChapterMeta) {
-                return null;
+                break;
             }
 
-            return [
-                'title' => $firstChapterMeta->getTitle(),
-                'link' => $firstChapterMeta->getUrl(),
-            ];
+            if ($filename === $parserFilename) {
+                $foundCurrentFile = true;
+            }
         }
 
-        [$toc, $indexCurrentFile] = $this->getNextPrevInformation($parserFilename);
-
-        if (!isset($toc[$indexCurrentFile + 1])) {
+        // no next document found!
+        if (null === $nextFileName) {
             return null;
         }
 
-        $nextFileName = $toc[$indexCurrentFile + 1];
-
-        $nextMeta = $this->getMetaEntry($nextFileName);
-
-        if (null === $nextMeta) {
-            return null;
-        }
+        $meta = $this->getMetaEntry($nextFileName);
 
         return [
-            'title' => $nextMeta->getTitle(),
-            'link' => $nextMeta->getUrl(),
+            'title' => $meta->getTitle(),
+            'link' => $meta->getUrl(),
         ];
     }
 
-    private function guessPrev(string $parserFilename): ?array
+    private function determinePrev(string $parserFilename, array $flattenedTocTree): ?array
     {
-        $meta = $this->getMetaEntry($parserFilename, true);
-        $parentFile = $meta->getParent();
-
-        [$toc, $indexCurrentFile] = $this->getNextPrevInformation($parserFilename);
-
-        // if current file is the first one of the chapter, prev is the direct parent
-        if (0 === $indexCurrentFile) {
-            $parentMeta = $this->getMetaEntry($parentFile);
-
-            if (null === $parentMeta) {
-                return null;
+        $previousFileName = null;
+        $foundCurrentFile = false;
+        foreach ($flattenedTocTree as $filename) {
+            if ($filename === $parserFilename) {
+                $foundCurrentFile = true;
+                break;
             }
 
-            return [
-                'title' => $parentMeta->getTitle(),
-                'link' => $parentMeta->getUrl(),
-            ];
+            $previousFileName = $filename;
         }
 
-        if (!isset($toc[$indexCurrentFile - 1])) {
+        // no previous document found!
+        if (null === $previousFileName || !$foundCurrentFile) {
             return null;
         }
 
-        $prevFileName = $toc[$indexCurrentFile - 1];
-
-        $prevMeta = $this->getMetaEntry($prevFileName);
-
-        if (null === $prevMeta) {
-            return null;
-        }
+        $meta = $this->getMetaEntry($previousFileName);
 
         return [
-            'title' => $prevMeta->getTitle(),
-            'link' => $prevMeta->getUrl(),
+            'title' => $meta->getTitle(),
+            'link' => $meta->getUrl(),
         ];
     }
 
-    private function getNextPrevInformation(string $parserFilename): ?array
+    private function getMetaEntry(string $parserFilename, bool $throwOnMissing = false): ?MetaEntry
     {
-        $meta = $this->getMetaEntry($parserFilename, true);
-        $parentFile = $meta->getParent();
+        $metaEntry = $this->metas->get($parserFilename);
 
-        if (!$parentFile) {
-            return [null, null];
-        }
+        // this is possible if there are invalid references
+        if (null === $metaEntry) {
+            $message = sprintf('Could not find MetaEntry for file "%s"', $parserFilename);
 
-        $metaParent = $this->getMetaEntry($parentFile);
+            if ($throwOnMissing) {
+                throw new \Exception($message);
+            }
 
-        if (null === $metaParent || !$metaParent->getTocs() || 1 !== \count($metaParent->getTocs())) {
-            return [null, null];
+            if ($this->output) {
+                $this->output->note($message);
+            }
         }
 
-        $toc = current($metaParent->getTocs());
+        return $metaEntry;
+    }
 
-        if (\count($toc) < 2 || !isset(array_flip($toc)[$parserFilename])) {
-            return [null, null];
-        }
+    /**
+     * Creates a hierarchy of documents by crawling the toctree's
+     *
+     * This looks at the
+     * toc tree of the master document, following the first entry
+     * like a link, then repeating the process on the next document's
+     * toc tree (if it has one). When it hits a dead end, it would
+     * go back to the master document and click the second link.
+     * But, it skips any links that have been seen before. This
+     * is the logic behind how the prev/next parent information is created.
+     *
+     * Example result:
+     *      [
+     *          'dashboards' => [],
+     *          'design' => [
+     *              'crud' => [],
+     *              'design/sub-page' => [],
+     *          ],
+     *          'fields' => []
+     *      ]
+     *
+     * See the JsonIntegrationTest for a test case.
+     */
+    private function walkTocTreeAndReturnHierarchy(string $filename, array &$walkedFiles): array
+    {
+        $hierarchy = [];
+        foreach ($this->getMetaEntry($filename)->getTocs() as $toc) {
+            foreach ($toc as $tocFilename) {
+                // only walk a file one time, the first time you see it
+                if (in_array($tocFilename, $walkedFiles, true)) {
+                    continue;
+                }
 
-        $indexCurrentFile = array_flip($toc)[$parserFilename];
+                $walkedFiles[] = $tocFilename;
+
+                $hierarchy[$tocFilename] = $this->walkTocTreeAndReturnHierarchy($tocFilename, $walkedFiles);
+            }
+        }
 
-        return [$toc, $indexCurrentFile];
+        return $hierarchy;
     }
 
-    private function getMetaEntry(string $parserFilename, bool $throwOnMissing = false): ?MetaEntry
+    /**
+     * Takes the structure from walkTocTreeAndReturnHierarchy() and flattens it.
+     *
+     * For example:
+     *
+     *      [dashboards, design, crud, design/sub-page, fields]
+     *
+     * @return string[]
+     */
+    private function flattenTocTree(array $tocTreeHierarchy): array
     {
-        $metaEntry = $this->metas->get($parserFilename);
+        $files = [];
 
-        // this is possible if there are invalid references
-        if (null === $metaEntry) {
-            $message = sprintf('Could not find MetaEntry for file "%s"', $parserFilename);
+        foreach ($tocTreeHierarchy as $filename => $tocTree) {
+            $files[] = $filename;
 
-            if ($throwOnMissing) {
-                throw new \Exception($message);
+            $files = array_merge($files, $this->flattenTocTree($tocTree));
+        }
+
+        return $files;
+    }
+
+    private function determineParents(string $parserFilename, array $tocTreeHierarchy, array $parents = []): ?array
+    {
+        foreach ($tocTreeHierarchy as $filename => $tocTree) {
+            if ($filename === $parserFilename) {
+                return $parents;
             }
 
-            if ($this->output) {
-                $this->output->note($message);
+            $subParents = $this->determineParents($parserFilename, $tocTree, $parents + [$filename]);
+
+            if (null !== $subParents) {
+                // the item WAS found and the parents were returned
+                return $subParents;
             }
         }
 
-        return $metaEntry;
+        // item was not found
+        return null;
     }
 }