From 64b07bfaf6e4846102eaa2ca006728a0186465a5 Mon Sep 17 00:00:00 2001 From: Tim Date: Thu, 15 Feb 2018 17:51:41 +1100 Subject: [PATCH 1/3] allow formatting and aside tags The group description was escaping everything by default meaning that the aside tag (which is quite useful) can't be used in a group header. This addresses that by no longer escaping the content, as is consistent with the rest of the library. --- src/resources/views/documentarian.blade.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resources/views/documentarian.blade.php b/src/resources/views/documentarian.blade.php index 9e2a136a..6d7a3c24 100644 --- a/src/resources/views/documentarian.blade.php +++ b/src/resources/views/documentarian.blade.php @@ -7,7 +7,7 @@ @foreach($parsedRoutes as $group => $routes) @if($group) -#{{$group}} +#{!! $group !!} @endif @foreach($routes as $parsedRoute) @if($writeCompareFile === true) From a8fc03126c9b3525ac058861762183667af18937 Mon Sep 17 00:00:00 2001 From: Tim Ogilvy Date: Tue, 20 Feb 2018 00:11:37 +1100 Subject: [PATCH 2/3] allow prepend and append markdown to address feature request #262 --- README.md | 9 +++++++++ .../ApiDoc/Commands/GenerateDocumentation.php | 16 ++++++++++++++++ src/resources/views/documentarian.blade.php | 8 ++++++-- 3 files changed, 31 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1452ea73..36476742 100644 --- a/README.md +++ b/README.md @@ -231,6 +231,15 @@ $ php artisan api:update As an optional parameter, you can use `--location` to tell the update command where your documentation can be found. +## automatically add markdown to the beginning or end of the documentation + +If you wish to automatically add the same content to the docs every time you generate, you can add a `prepend.md` and/or `append.md` file to the source folder, and they will be included either above, or below the generated routes (or both). + +**File locations:** +`public/docs/source/prepend.md` +`public/docs/source/append.md` + + ## Skip single routes If you want to skip a single route from a list of routes that match a given prefix, you can use the `@hideFromAPIDocumentation` tag on the Controller method you do not want to document. diff --git a/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php b/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php index 857be1ca..cf964fe3 100644 --- a/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php +++ b/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php @@ -103,6 +103,8 @@ private function writeMarkdown($parsedRoutes) $outputPath = $this->option('output'); $targetFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'index.md'; $compareFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'.compare.md'; + $prependFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'prepend.md'; + $appendFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'append.md'; $infoText = view('apidoc::partials.info') ->with('outputPath', ltrim($outputPath, 'public/')) @@ -152,12 +154,24 @@ private function writeMarkdown($parsedRoutes) }); } + $prependFileContents = ""; + if (file_exists($prependFile)) { + $prependFileContents = file_get_contents($prependFile); + } + + $appendFileContents = ""; + if (file_exists($appendFile)) { + $appendFileContents = file_get_contents($appendFile); + } + $documentarian = new Documentarian(); $markdown = view('apidoc::documentarian') ->with('writeCompareFile', false) ->with('frontmatter', $frontmatter) ->with('infoText', $infoText) + ->with('prependMd', $prependFileContents) + ->with('appendMd', $appendFileContents) ->with('outputPath', $this->option('output')) ->with('showPostmanCollectionButton', ! $this->option('noPostmanCollection')) ->with('parsedRoutes', $parsedRouteOutput); @@ -174,6 +188,8 @@ private function writeMarkdown($parsedRoutes) ->with('writeCompareFile', true) ->with('frontmatter', $frontmatter) ->with('infoText', $infoText) + ->with('prependMd', $prependFileContents) + ->with('appendMd', $appendFileContents) ->with('outputPath', $this->option('output')) ->with('showPostmanCollectionButton', ! $this->option('noPostmanCollection')) ->with('parsedRoutes', $parsedRouteOutput); diff --git a/src/resources/views/documentarian.blade.php b/src/resources/views/documentarian.blade.php index 6d7a3c24..83d7c37d 100644 --- a/src/resources/views/documentarian.blade.php +++ b/src/resources/views/documentarian.blade.php @@ -5,15 +5,19 @@ {!! $infoText !!} +{!! $prependMd !!} + @foreach($parsedRoutes as $group => $routes) @if($group) -#{!! $group !!} +#{{$group}} @endif @foreach($routes as $parsedRoute) @if($writeCompareFile === true) -{!! $parsedRoute['output']!!} +{!! $parsedRoute['output'] !!} @else {!! isset($parsedRoute['modified_output']) ? $parsedRoute['modified_output'] : $parsedRoute['output']!!} @endif @endforeach @endforeach + +{!! $appendMd !!} From 5b632f72e6166856c877b7db82c7e10f579b47f9 Mon Sep 17 00:00:00 2001 From: Tim Ogilvy Date: Tue, 20 Feb 2018 00:26:34 +1100 Subject: [PATCH 3/3] style compliance --- src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php b/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php index cf964fe3..99e68c9a 100644 --- a/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php +++ b/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php @@ -154,12 +154,12 @@ private function writeMarkdown($parsedRoutes) }); } - $prependFileContents = ""; + $prependFileContents = ''; if (file_exists($prependFile)) { $prependFileContents = file_get_contents($prependFile); } - $appendFileContents = ""; + $appendFileContents = ''; if (file_exists($appendFile)) { $appendFileContents = file_get_contents($appendFile); }