HtmlWriter.php 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128
  1. <?php
  2. namespace Knuckles\Scribe\Writing;
  3. use Illuminate\Support\Facades\View;
  4. use Knuckles\Scribe\Tools\DocumentationConfig;
  5. use Knuckles\Scribe\Tools\Globals;
  6. use Knuckles\Scribe\Tools\Utils;
  7. use Knuckles\Scribe\Tools\WritingUtils;
  8. use Parsedown;
  9. /**
  10. * Transforms the extracted data (endpoints YAML, API details Markdown) into a HTML site
  11. */
  12. class HtmlWriter
  13. {
  14. protected DocumentationConfig $config;
  15. protected string $baseUrl;
  16. protected Parsedown $markdownParser;
  17. public function __construct(DocumentationConfig $config = null)
  18. {
  19. $this->config = $config ?: new DocumentationConfig(config('scribe', []));
  20. $this->markdownParser = new Parsedown();
  21. $this->baseUrl = $this->config->get('base_url') ?? config('app.url');
  22. }
  23. public function generate(array $groupedEndpoints, string $sourceFolder, string $destinationFolder)
  24. {
  25. $intro = $this->transformMarkdownFileToHTML($sourceFolder . '/intro.md');
  26. $auth = $this->transformMarkdownFileToHTML($sourceFolder . '/auth.md');
  27. $appendFile = rtrim($sourceFolder, '/') . '/' . 'append.md';
  28. $append = file_exists($appendFile) ? $this->transformMarkdownFileToHTML($appendFile) : '';
  29. // If they're using the default static path,
  30. // then use '../docs/{asset}', so assets can work via Laravel app or via index.html
  31. $assetPathPrefix = '../docs/';
  32. if ($this->config->get('type') == 'static'
  33. && rtrim($this->config->get('static.output_path', ''), '/') != 'public/docs'
  34. ) {
  35. $assetPathPrefix = './';
  36. }
  37. $theme = $this->config->get('theme') ?? 'default';
  38. $output = View::make("scribe::themes.$theme.index", [
  39. 'metadata' => $this->getMetadata(),
  40. 'baseUrl' => $this->baseUrl,
  41. 'tryItOut' => $this->config->get('try_it_out'),
  42. 'intro' => $intro,
  43. 'auth' => $auth,
  44. 'groupedEndpoints' => $groupedEndpoints,
  45. 'append' => $append,
  46. 'assetPathPrefix' => $assetPathPrefix,
  47. ])->render();
  48. if (!is_dir($destinationFolder)) {
  49. mkdir($destinationFolder, 0777, true);
  50. }
  51. file_put_contents($destinationFolder . '/index.html', $output);
  52. // Copy assets
  53. $assetsFolder = __DIR__ . '/../../resources';
  54. if (is_dir($assetsFolder)) {
  55. // Prune older versioned assets
  56. Utils::deleteDirectoryAndContents($assetsFolder);
  57. }
  58. Utils::copyDirectory("{$assetsFolder}/images/", "{$destinationFolder}/images");
  59. $assets = [
  60. "{$assetsFolder}/css/theme-$theme.style.css" => ["$destinationFolder/css/", "theme-$theme.style.css"],
  61. "{$assetsFolder}/css/theme-$theme.print.css" => ["$destinationFolder/css/", "theme-$theme.print.css"],
  62. "{$assetsFolder}/js/theme-$theme.js" => ["$destinationFolder/js/", WritingUtils::getVersionedAsset("theme-$theme.js")],
  63. ];
  64. foreach ($assets as $path => [$destination, $fileName]) {
  65. if (file_exists($path)) {
  66. if (!is_dir($destination)) {
  67. mkdir($destination, 0777, true);
  68. }
  69. copy($path, $destination.$fileName);
  70. }
  71. }
  72. if ($this->config->get('try_it_out.enabled', true)) {
  73. copy("{$assetsFolder}/js/tryitout.js", $destinationFolder . WritingUtils::getVersionedAsset('/js/tryitout.js'));
  74. }
  75. }
  76. protected function transformMarkdownFileToHTML(string $markdownFilePath): string
  77. {
  78. return $this->markdownParser->text(file_get_contents($markdownFilePath));
  79. }
  80. protected function getMetadata(): array
  81. {
  82. $links = [];
  83. // NB:These paths are wrong for laravel type but will be set correctly by the Writer class
  84. if ($this->config->get('postman.enabled', true)) {
  85. $links[] = '<a href="../docs/collection.json">View Postman collection</a>';
  86. }
  87. if ($this->config->get('openapi.enabled', false)) {
  88. $links[] = '<a href="../docs/openapi.yaml">View OpenAPI spec</a>';
  89. }
  90. $auth = $this->config->get('auth');
  91. if ($auth['in'] === 'bearer' || $auth['in'] === 'basic') {
  92. $auth['name'] = 'Authorization';
  93. $auth['location'] = 'header';
  94. $auth['prefix'] = ucfirst($auth['in']).' ';
  95. } else {
  96. $auth['location'] = $auth['in'];
  97. $auth['prefix'] = '';
  98. }
  99. return [
  100. 'title' => $this->config->get('title') ?: config('app.name', '') . ' Documentation',
  101. 'example_languages' => $this->config->get('example_languages'),
  102. 'logo' => $this->config->get('logo') ?? false,
  103. 'last_updated' => date("F j Y"),
  104. 'auth' => $auth,
  105. 'try_it_out' => $this->config->get('try_it_out'),
  106. 'links' => array_merge($links, ['<a href="http://github.com/knuckleswtf/scribe">Documentation powered by Scribe ✍</a>']),
  107. ];
  108. }
  109. }