Ready for next version

docs/getting-started/using-the-config-file.md

@@ -4,3 +4,54 @@ If there is a roster.json file in your project root, Roster will attempt to use
 
 ## Configuration Schema
 
+The repository contains a JSON Schema definition, in JSON Schema version 7.
+
+This file can be downloaded from here:
+
+[https://raw.githubusercontent.com/JordanRL/Roster/master/roster-config-schema.config.json](https://raw.githubusercontent.com/JordanRL/Roster/master/roster-config-schema.config.json)
+
+This can be used to help your IDE validate your configuration file as you create it.
+
+## Example Config File With All Options
+
+Below is an example config file with all options given values to illustrate how the config file can be written.
+
+```json
+{
+  "prefer-source": false,
+  "with-version": "v0.2",
+  "templates": "doc-templates/roster-templates-mkdocs",
+  "mkdocs": {
+    "site-name": "Roster - Docs From The Source",
+    "site-url": "https://jordanrl.github.io/Roster/",
+    "repo-url": "https://github.com/JordanRL/Roster/",
+    "theme": "sphinx-rtd",
+    "auto-deploy": true,
+    "merge-nav": true,
+    "merge-nav-mode": "replace-nav-key",
+    "nav-key": "Source Reference"
+  },
+  "sources": [
+    {
+      "path": "./src",
+      "visibility": "protected",
+      "aliases": [
+        {
+          "namespace": "Samsara\\Roster\\",
+          "alias": "Core\\"
+        }
+      ]
+    },
+    {
+      "path": "../RosterModule/src",
+      "visibility": "public",
+      "aliases": [
+        {
+          "namespace": "Samsara\\Roster\\",
+          "alias": "Module\\"
+        }
+      ]
+    }
+  ]
+}
+```

docs/index.md

@@ -1,5 +1,10 @@
 # Roster | Docs From The Source
 
+!!! tip "Check It Out!"
+    **This documentation was built and deployed by running one command:**
+
+    `php vendor/bin/roster`
+
 Roster is a PHP command line program that allows you to build documentation from your code. It inspects the files in your codebase and looks at the PHPDoc comments associated with them, and then builds documentation in Markdown.
 
 But it doesn't have to.

docs/roster/latest/Roster/Roster.md

@@ -312,7 +312,7 @@ Class Roster
     **return**
 
     type
-    :   void
+    :   bool
 
     description
     :   *No description available*
@@ -331,7 +331,7 @@ Class Roster
     **return**
 
     type
-    :   void
+    :   bool
 
     description
     :   *No description available*

docs/roster/latest/Roster/TemplateFactory.md

@@ -28,7 +28,7 @@
     **return**
 
     type
-    :   *mixed* (assumed)
+    :   bool
 
     description
     :   *No description available*
@@ -158,7 +158,7 @@
     **return**
 
     type
-    :   *mixed* (assumed)
+    :   bool
 
     description
     :   *No description available*

mkdocs.yml

@@ -12,6 +12,8 @@ nav:
                 Installation: getting-started/installation.md
             -
                 'Using the Command': getting-started/using-the-command.md
+            -
+                'Using the Config File': getting-started/using-the-config-file.md
     -
         'Source Reference':
             -

roster.json

@@ -1,4 +1,7 @@
 {
+  "prefer-source": false,
+  "with-version": "latest",
+  "templates": "doc-templates/roster-templates-mkdocs",
   "mkdocs": {
     "site-name": "Roster - Docs From The Source",
     "site-url": "https://jordanrl.github.io/Roster/",
@@ -13,10 +16,12 @@
     {
       "path": "./src",
       "visibility": "protected",
-      "aliases": [{
-        "namespace": "Samsara\\Roster\\",
-        "alias": "Roster\\"
-      }]
+      "aliases": [
+        {
+          "namespace": "Samsara\\Roster\\",
+          "alias": "Roster\\"
+        }
+      ]
     }
   ]
 }

src/Samsara/Roster/Roster.php

@@ -33,7 +33,6 @@ class Roster extends Command
 {
 
     private array $classes = [];
-    private array $classesProcessed = [];
 
     /** @var ReflectionClass[][] */
     private array $reflectors = [];
@@ -385,6 +384,8 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $baseExportPathParts = explode('/', $baseExportPath);
         $pathSum = '';
 
+        $this->io->section('Initialization');
+
         foreach ($baseExportPathParts as $exportPathPart) {
             $pathSum .= '/'.$exportPathPart;
             if (!is_dir($pathSum)) {
@@ -398,13 +399,15 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             }
         }
 
+        $ok = $this->processTemplates(ConfigBag::getRosterConfig()->get('templates'));
 
-        if ($this->verbose) {
-            $this->io->section('Initialization');
+        if (!$ok) {
+            $this->io->error('Could not initialize Roster');
+            return self::FAILURE;
+        } else {
+            $this->io->success('Roster Initialized');
         }
 
-        $this->processTemplates(ConfigBag::getRosterConfig()->get('templates'));
-
         foreach ($sources as $source) {
             $aliasFrom = [];
             $aliasTo = [];
@@ -437,13 +440,13 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
             $fileList = $this->traverseDirectories(realpath($this->rootDir.'/'.$sourcePath));
 
-            $this->classesProcessed = $this->classes;
             $this->classes = [];
             foreach ($fileList as $file) {
                 $this->extractFileData($file);
             }
 
-            $this->createReflectors();
+            $this->reflectors = [];
+            $ok = $this->createReflectors();
 
             if (!TemplateFactory::hasTemplate('class')) {
                 $this->io->error('Could not load templates');
@@ -490,11 +493,21 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $this->io->progressFinish();
         }
 
+        $this->io->warning('Some Classes Were Skipped');
+
         $this->io->section('Compiling');
         TemplateFactory::compileAll($this->io);
 
+        $this->io->success('Templates Compiled To Documents');
+
         $this->io->section('Writing Documentation to Output Directory');
-        TemplateFactory::writeToDocs($baseExportPath, $this->io);
+        $ok = TemplateFactory::writeToDocs($baseExportPath, $this->io);
+
+        if ($ok) {
+            $this->io->success('Documentation Written To Output Directory');
+        } else {
+            $this->io->warning('Some Files Could Not Be Written');
+        }
 
         if (ConfigBag::getRosterConfig()->has('mkdocs')) {
             $cssFileName = ConfigBag::getRosterConfig()->get('mkdocs.theme').'-theme';
@@ -548,11 +561,11 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             } else {
                 if (isset($oldConfig) && !$choice) {
                     $oldMkdocs = file_get_contents($this->rootDir . '/mkdocs.yml');
-                    file_put_contents($this->rootDir . '/mkdocs.yml.old', $oldMkdocs);
+                    $ok = file_put_contents($this->rootDir . '/mkdocs.yml.old', $oldMkdocs);
                 }
 
                 $configBase = Config::load(
-                    TemplateFactory::getTemplate('mkdocs')->compile(),
+                    TemplateFactory::getTemplate('mkdocs-'.ConfigBag::getRosterConfig()->get('mkdocs.theme'))->compile(),
                     new YamlReader(),
                     true
                 );
@@ -569,19 +582,43 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             }
 
             if (!is_dir($this->rootDir.'/docs/css')) {
-                mkdir($this->rootDir . '/docs/css');
+                $ok = $ok && mkdir($this->rootDir . '/docs/css');
+            }
+
+            if ($ok) {
+                $this->io->success('MkDocs Configured');
+            } else {
+                $this->io->error('MkDocs Configuration Failed');
+                $this->io->writeln('Aborting to preserve your existing configuration');
+                return self::FAILURE;
             }
 
             TemplateFactory::queueCompile('docs/css/'.$cssFileName, TemplateFactory::getTemplate($cssFileName), 'css');
             TemplateFactory::queueCompile('docs/requirements', TemplateFactory::getTemplate('requirements'), 'txt');
 
-            $this->io->section('Exporting Additional Files');
+            $this->io->newLine();
+            $this->io->writeln('<comment>Exporting Additional Files</>');
+            $this->io->newLine();
             TemplateFactory::compileAll($this->io);
 
-            TemplateFactory::writeToDocs($this->rootDir, $this->io);
+            $ok = TemplateFactory::writeToDocs($this->rootDir, $this->io);
+
+            if ($ok) {
+                $this->io->success('Supporting Files Exported');
+            } else {
+                $this->io->warning('Supporting Files Could Not Be Exported');
+            }
+
+            $this->io->newLine();
+            $this->io->writeln('<comment>Writing MkDocs Config</>');
+            $this->io->newLine();
+            $ok = file_put_contents($this->rootDir.'/mkdocs.yml', $mkDocsConfig);
 
-            $this->io->section('Writing MkDocs Config');
-            file_put_contents($this->rootDir.'/mkdocs.yml', $mkDocsConfig);
+            if ($ok) {
+                $this->io->success('MkDocs Config File Updated');
+            } else {
+                $this->io->warning('MkDocs Config File Could Not Be Updated');
+            }
         }
 
         $summary = [];
@@ -602,18 +639,25 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $summary[] = 'Documents MkDocs Ready: <fg=yellow>No</>';
         }
 
-        $this->io->success('Documentation Built');
         foreach ($summary as $message) {
             $this->io->writeln($message);
         }
 
-        if (ConfigBag::getRosterConfig()->has('auto-deploy')) {
-            if (ConfigBag::getRosterConfig()->get('auto-deploy')) {
+        $this->io->success('Documentation Built');
+
+        if (ConfigBag::getRosterConfig()->has('mkdocs.auto-deploy')) {
+            if (ConfigBag::getRosterConfig()->get('mkdocs.auto-deploy')) {
                 $this->io->section('Deploying To GH Pages Using MkDocs');
-                while ($output = exec('mkdocs gh-deploy')) {
-                    $this->io->writeln($output);
+
+                $output = exec('mkdocs gh-deploy', $null, $deployCode);
+
+                $this->io->writeln($output);
+
+                if ($deployCode === 0) {
+                    $this->io->success('Documentation Deployed');
+                } else {
+                    $this->io->error('Documentation Could Not Be Auto-Deployed');
                 }
-                $this->io->success('Documentation Deployed');
             }
         }
 
@@ -843,9 +887,12 @@ protected function extractFileData(string $realPath): void
 
     }
 
-    protected function createReflectors(): void
+    protected function createReflectors(): bool
     {
 
+        $ok = true;
+        $reflectorCount = 0;
+
         foreach ($this->classes as $namespace => $itemType) {
             foreach ($itemType as $type => $names) {
                 foreach ($names as $name) {
@@ -860,12 +907,25 @@ protected function createReflectors(): void
                     if ($type == 'trait') {
                         $this->reflectors['traits'][] = new \ReflectionClass('\\'.$namespace.'\\'.$name);
                     }
+
+                    $reflectorCount++;
                 }
             }
         }
+
+        $classCount = 0;
+        $classCount += array_key_exists('classes', $this->classes) ? count($this->classes['classes']) : 0;
+        $classCount += array_key_exists('interfaces', $this->classes) ? count($this->classes['interfaces']) : 0;
+        $classCount += array_key_exists('traits', $this->classes) ? count($this->classes['traits']) : 0;
+
+        if ($classCount != $reflectorCount) {
+            $ok = false;
+        }
+
+        return $ok;
     }
 
-    protected function processTemplates(string $templatePath): void
+    protected function processTemplates(string $templatePath): bool
     {
 
         if (!is_dir($templatePath)) {
@@ -877,22 +937,27 @@ protected function processTemplates(string $templatePath): void
                 $this->io->error('Cannot find Roster templates.');
                 $this->io->info('Please provide a path to the templates directory using the --templates option.');
 
-                return;
+                return false;
             }
         }
         $fileList = $this->traverseDirectories($templatePath);
 
         $this->io->section('Loading Templates');
         $this->io->progressStart(count($fileList));
+
+        $ok = true;
+
         foreach ($fileList as $file) {
             $pathInfo = pathinfo($file);
 
-            TemplateFactory::pushTemplate($file, $pathInfo['extension']);
+            $ok = $ok && TemplateFactory::pushTemplate($file, $pathInfo['extension']);
             $this->io->progressAdvance();
 
         }
         $this->io->progressFinish();
 
+        return $ok;
+
     }
 
 }