Skip to content

Commit

Permalink
Ready for next version
Browse files Browse the repository at this point in the history
JordanRL committed Jul 8, 2021
1 parent 893432e commit e708a7a
Showing 9 changed files with 179 additions and 37 deletions.
51 changes: 51 additions & 0 deletions docs/getting-started/using-the-config-file.md
Original file line number Diff line number Diff line change
@@ -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\\"
}
]
}
]
}
```
5 changes: 5 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -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.
4 changes: 2 additions & 2 deletions docs/roster/latest/Roster/Roster.md
Original file line number Diff line number Diff line change
@@ -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*
4 changes: 2 additions & 2 deletions docs/roster/latest/Roster/TemplateFactory.md
Original file line number Diff line number Diff line change
@@ -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*
2 changes: 2 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -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':
-
13 changes: 9 additions & 4 deletions roster.json
Original file line number Diff line number Diff line change
@@ -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\\"
}
]
}
]
}
115 changes: 90 additions & 25 deletions src/Samsara/Roster/Roster.php
Original file line number Diff line number Diff line change
@@ -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;

}

}
Loading

0 comments on commit e708a7a

Please sign in to comment.