From f02f31475b3fed8255e5f4c26341c10fc2bdd941 Mon Sep 17 00:00:00 2001 From: Jordan LeDoux Date: Tue, 6 Jul 2021 10:57:49 -0700 Subject: [PATCH] Updated mkdocs export to keep desc consistent --- .../css/roster-style.css | 441 +++++------------- .../snippets/classInterface.md | 2 +- .../snippets/method.md | 6 +- .../snippets/staticMethod.md | 6 +- .../Processors/InterfaceInlineProcessor.php | 4 + .../MethodArgumentDetailProcessor.php | 4 + .../Roster/Processors/MethodProcessor.php | 8 +- .../Processors/TraitInlineProcessor.php | 8 + src/Samsara/Roster/TemplateFactory.php | 22 + 9 files changed, 166 insertions(+), 335 deletions(-) diff --git a/doc-templates/roster-templates-mkdocs/css/roster-style.css b/doc-templates/roster-templates-mkdocs/css/roster-style.css index 622b980..9d59488 100644 --- a/doc-templates/roster-templates-mkdocs/css/roster-style.css +++ b/doc-templates/roster-templates-mkdocs/css/roster-style.css @@ -1,164 +1,121 @@ @import url('https://fonts.googleapis.com/css2?family=Source+Code+Pro:wght@400;500;700&display=swap'); :root { - --icon-signature: url('data:image/svg+xml;charset=UTF-8,'); + --md-admonition-icon--signature: url('data:image/svg+xml;charset=utf-8,'); + --md-adminition-icon--signature-constant: url('data:image/svg+xml;charset=utf-8,'); + --md-adminition-icon--signature-property: url('data:image/svg+xml;charset=utf-8,'); + --md-adminition-icon--signature-interface: url('data:image/svg+xml;charset=utf-8,'); + --md-adminition-icon--signature-trait: url('data:image/svg+xml;charset=utf-8,'); } -.codehilite { - background: rgba(0, 0, 0, 0.05); -} - -code { - font-family: "Source Code Pro"; - font-weight: 500; - background: #333; - color: #EEE; - font-size: 95%; -} - -li code { +.md-content .signature { + padding: 0; + margin-bottom: 12px; + box-sizing: border-box; + border-left-color: #cceeff; background: inherit; - color: inherit; - font-weight: 700; - border: none; - padding: inherit; -} - -ul.subnav li span.caption-text { - padding-left: 2.618em; } -ul.subnav ul.subnav ul { - margin-left: 1em; +.md-content .signature p { + margin-left: 10px; } -h1 { - background: #FFFFFF; - border-left: 5px solid #000000; - border-bottom: 5px solid #000000; - border-radius: 3px; - color: #333333; - padding: 2px 12px; - box-shadow: 0 0 .5rem rgba(0,0,0,.15),0 0 .05rem rgba(0,0,0,.25); +.md-content .signature dl { + display: flex; + flex-direction: row; + flex-wrap: wrap; + margin: 0; } -h2 { - background: #FFFFFF; - border-left: 5px solid #000000; - border-radius: 3px; - color: #333333; - padding: 0 12px; - box-shadow: 0 0 .5rem rgba(0,0,0,.15),0 0 .05rem rgba(0,0,0,.25); +.md-content .signature dl dt { + background: inherit; + flex-basis: 20%; + flex-grow: 0; + text-align: right; + border-top: 0; + border-right: 2px solid #999999; + margin: 0 0 6px 0; + line-height: 24px; + color: #999999; + font-size: 14px; + padding-right: 5px; + padding-top: 7px; + font-family: "Source Code Pro"; } -h3 { - border-bottom: 3px solid rgba(0, 0, 0, 0.45); +.md-content .signature dl dd { + flex-basis: 80%; + flex-grow: 0; + padding-left: 15px; + padding-top: 6px; + padding-bottom: 6px; + margin: 0 0 6px 0; + font-size: 14px; + background: inherit; + word-wrap: anywhere; + font-family: "Source Code Pro"; } -h4 { - font-variant-caps: all-small-caps; +.md-content .signature dl dd ul { + margin-bottom: 0 !important; } -h6 { +.md-content .signature .admonition-title { + background: inherit; font-family: 'Source Code Pro'; font-weight: 500; font-size: 16px; - border-bottom: 1px solid #000; + line-height: 20px; + border-bottom: 0; + border-left: 0; padding-bottom: 5px; + padding-right: 0; + margin-left: 0; + margin-right: 0; + margin-top: 0; + margin-bottom: 6px; } -h6::before { - content: ""; - font-family: "FontAwesome"; - display: inline-block; - font-style: normal; - font-weight: normal; - line-height: 1; - text-decoration: inherit; - font-size: 16px; - margin-right: 4px; - color: #00c853; -} - -div.highlight, .tabbed-set .highlight { - border: 0; - background: inherit; -} - -.tabbed-set .highlight { - margin-top: 12px; -} - -div.highlight pre { - border: 0; - font-family: "Source Code Pro"; -} - -div.highlight pre span.lineno { - border-right: 1px solid #333; - margin-right: 5px; - display: inline-block; - width: 1.5em; - color: #999; +.md-typeset .signature > .admonition-title::before, +.md-typeset .signature > summary::before { + background-color: #00c853; + -webkit-mask-image: var(--md-admonition-icon--signature); + mask-image: var(--md-admonition-icon--signature); } -.tabbed-set .highlight pre:last-child, -.rst-content .admonition .highlight:last-child, -.tabbed-set div:last-child { - margin-bottom: 0; +.md-typeset .signature.constant > .admonition-title::before, +.md-typeset .signature.constant > summary::before { + background-color: #00c853; + -webkit-mask-image: var(--md-adminition-icon--signature-constant); + mask-image: var(--md-adminition-icon--signature-constant); } -.rst-content .admonition { - padding: 12px; - line-height: 24px; - margin-bottom: 24px; - background: #FFFFFF; - border-left: 5px solid #000000; - border-radius: 3px; - box-shadow: 0 0 .5rem rgba(0,0,0,.15),0 0 .05rem rgba(0,0,0,.25); - color: #000000; +.md-typeset .signature.property > .admonition-title::before, +.md-typeset .signature.property > summary::before { + background-color: #00c853; + -webkit-mask-image: var(--md-adminition-icon--signature-property); + mask-image: var(--md-adminition-icon--signature-property); } -.rst-content .admonition p:last-child { - margin-bottom: 0; +.md-typeset .signature.interface > .admonition-title::before, +.md-typeset .signature.interface > summary::before { + background-color: #00c853; + -webkit-mask-image: var(--md-adminition-icon--signature-interface); + mask-image: var(--md-adminition-icon--signature-interface); } -.rst-content .admonition-title { - color: #333333; -} - -.rst-content .footer-link { - padding: 0; - margin-bottom: 12px; - box-sizing: border-box; - border: 0; - box-shadow: none; - background: inherit; -} - -.rst-content .footer-link .admonition-title { - background: inherit; - font-family: 'sans-serif'; - font-style: italic; - font-weight: 500; - font-size: 12px; - line-height: 12px; - border-bottom: 0; - padding-bottom: 5px; - padding-left: 0; - padding-right: 0; - margin-left: 0; - margin-right: 0; - margin-top: 0; - margin-bottom: 6px; +.md-typeset .signature.trait > .admonition-title::before, +.md-typeset .signature.trait > summary::before { + background-color: #00c853; + -webkit-mask-image: var(--md-adminition-icon--signature-trait); + mask-image: var(--md-adminition-icon--signature-trait); } .rst-content .signature { padding: 0; margin-bottom: 12px; box-sizing: border-box; - border: 0; - box-shadow: none; + border-left-color: #cceeff; background: inherit; } @@ -166,10 +123,6 @@ div.highlight pre span.lineno { margin-left: 10px; } -svg.fa-signature path { - fill: #00c853; -} - .rst-content .signature dl { display: flex; flex-direction: row; @@ -188,6 +141,8 @@ svg.fa-signature path { line-height: 24px; color: #999999; font-size: 14px; + padding-right: 5px; + padding-top: 7px; font-family: "Source Code Pro"; } @@ -200,6 +155,7 @@ svg.fa-signature path { margin: 0 0 6px 0; font-size: 14px; background: inherit; + word-wrap: anywhere; font-family: "Source Code Pro"; } @@ -212,10 +168,10 @@ svg.fa-signature path { font-family: 'Source Code Pro'; font-weight: 500; font-size: 16px; - line-height: 16px; + line-height: 20px; border-bottom: 0; + border-left: 0; padding-bottom: 5px; - padding-left: 0; padding-right: 0; margin-left: 0; margin-right: 0; @@ -223,214 +179,37 @@ svg.fa-signature path { margin-bottom: 6px; } -.rst-content .signature .admonition-title::before { - content: ""; - font-family: "FontAwesome"; - margin-right: 4px; - margin-left: 10px; - color: #00c853; - position: relative; - top: 2px; - font-size: 20px; - width: 20px; -} - -.rst-content .signature.constant .admonition-title::before { - content: ""; -} - -.rst-content .signature.property .admonition-title::before { - content: ""; -} - -.rst-content .signature.interface .admonition-title::before { - content: ""; -} - -.rst-content .signature.trait .admonition-title::before { - content: ""; -} - -.rst-content .note { - border-color: #00bfa5; -} - -.rst-content .note .admonition-title { - background: #ddFFEE; -} - -.rst-content .note .admonition-title::before { - content: ""; - color: #00bfa5; -} - -.note .tabbed-set input:nth-child(n+1):checked + label { - color: #00bfa5; - border-bottom: 3px solid #00bfa5; -} - -.rst-content .caution { - border-color: #ffa733; -} - -.rst-content .caution .admonition-title { - background: #ffeed9; -} - -.rst-content .caution .admonition-title::before { - content: ""; - color: #ffa733; -} - -.caution .tabbed-set input:nth-child(n+1):checked + label { - color: #ffa733; - border-bottom: 3px solid #ffa733; -} - -.rst-content .tip { - border-color: #00c853; -} - -.rst-content .tip .admonition-title { - background: #CCFFDD; -} - -.rst-content .tip .admonition-title::before { - content: ""; - color: #00c853; -} - -.tip .tabbed-set input:nth-child(n+1):checked + label { - color: #00c853; - border-bottom: 3px solid #00c853; -} - -.rst-content .example { - border-color: #8b33ff; -} - -.rst-content .example .admonition-title { - background: #e9d9ff; -} - -.rst-content .example .admonition-title::before { - content: ""; - color: #8b33ff; -} - -.example .tabbed-set input:nth-child(n+1):checked + label { - color: #8b33ff; - border-bottom: 3px solid #8b33ff; -} - -.rst-content .warning { - border-color: #ffa733; -} - -.rst-content .warning .admonition-title { - background: #ffeed9; -} - -.rst-content .warning .admonition-title::before { - content: ""; - color: #ffa733; -} - -.warning .tabbed-set input:nth-child(n+1):checked + label { - color: #ffa733; - border-bottom: 3px solid #ffa733; -} - -.rst-content .danger { - border-color: #ff3344; -} - -.rst-content .danger .admonition-title { - background: #ffe6e8; -} - -.rst-content .danger .admonition-title::before { - content: ""; - color: #ff3344; -} - -.danger .tabbed-set input:nth-child(n+1):checked + label { - color: #ff3344; - border-bottom: 3px solid #ff3344; -} - -.rst-content .see-also { - border-color: #338fff; -} - -.rst-content .see-also .admonition-title { - background: #d9ebff; -} - -.rst-content .see-also .admonition-title::before { - content: ""; - color: #338fff; -} - -.see-also .tabbed-set input:nth-child(n+1):checked + label { - color: #338fff; - border-bottom: 3px solid #338fff; -} - -.rst-content .potential-bugs { - border-color: #ff33b1; -} - -.rst-content .potential-bugs .admonition-title { - background: #ffe6f6; -} - -.rst-content .potential-bugs .admonition-title::before { - content: ""; - color: #ff33b1; -} - -.potential-bugs .tabbed-set input:nth-child(n+1):checked + label { - color: #ff33b1; - border-bottom: 3px solid #ff33b1; -} - -.tabbed-set { - display: flex; - position: relative; - flex-wrap: wrap; -} - -.tabbed-set .tabbed-content { - display: none; - order: 99; - width: 100%; -} - -.tabbed-set label { - width: auto; - margin: 0 0.5em; - padding: 0.25em; - font-size: 95%; - font-weight: bold; - font-variant: small-caps; - cursor: pointer; +.rst-content .signature > .admonition-title::before, +.rst-content .signature > summary::before { + background-color: #00c853; + -webkit-mask-image: var(--md-admonition-icon--signature); + mask-image: var(--md-admonition-icon--signature); } -.tabbed-set input { - position: absolute; - opacity: 0; +.rst-content .signature.constant > .admonition-title::before, +.rst-content .signature.constant > summary::before { + background-color: #00c853; + -webkit-mask-image: var(--md-adminition-icon--signature-constant); + mask-image: var(--md-adminition-icon--signature-constant); } -.tabbed-set input:nth-child(n+1) { - color: #333333; +.rst-content .signature.property > .admonition-title::before, +.rst-content .signature.property > summary::before { + background-color: #00c853; + -webkit-mask-image: var(--md-adminition-icon--signature-property); + mask-image: var(--md-adminition-icon--signature-property); } -.tabbed-set input:nth-child(n+1):checked + label { - color: #00bfa5; - border-bottom: 3px solid #00bfa5; +.rst-content .signature.interface > .admonition-title::before, +.rst-content .signature.interface > summary::before { + background-color: #00c853; + -webkit-mask-image: var(--md-adminition-icon--signature-interface); + mask-image: var(--md-adminition-icon--signature-interface); } -.tabbed-set input:nth-child(n+1):checked + label + .tabbed-content { - display: block; +.rst-content .signature.trait > .admonition-title::before, +.rst-content .signature.trait > summary::before { + background-color: #00c853; + -webkit-mask-image: var(--md-adminition-icon--signature-trait); + mask-image: var(--md-adminition-icon--signature-trait); } \ No newline at end of file diff --git a/doc-templates/roster-templates-mkdocs/snippets/classInterface.md b/doc-templates/roster-templates-mkdocs/snippets/classInterface.md index 5040f04..fa0be30 100644 --- a/doc-templates/roster-templates-mkdocs/snippets/classInterface.md +++ b/doc-templates/roster-templates-mkdocs/snippets/classInterface.md @@ -1,4 +1,4 @@ -!!! signature trait "{$interfaceName}" +!!! signature interface "{$interfaceName}" namespace : {$interfaceNamespace} diff --git a/doc-templates/roster-templates-mkdocs/snippets/method.md b/doc-templates/roster-templates-mkdocs/snippets/method.md index 6bb04b3..961ecfa 100644 --- a/doc-templates/roster-templates-mkdocs/snippets/method.md +++ b/doc-templates/roster-templates-mkdocs/snippets/method.md @@ -8,7 +8,11 @@ description : {$methodReturnDesc}{$hasDesc} -{$methodDescription}{hasDesc$}{$hasExample} + **{$className}{$connector}{$methodName} Description** + + {$methodDescription}{hasDesc$}{$hasExample} !!! example "Example" {$methodExample}{hasExample$} + +--- diff --git a/doc-templates/roster-templates-mkdocs/snippets/staticMethod.md b/doc-templates/roster-templates-mkdocs/snippets/staticMethod.md index 6bb04b3..961ecfa 100644 --- a/doc-templates/roster-templates-mkdocs/snippets/staticMethod.md +++ b/doc-templates/roster-templates-mkdocs/snippets/staticMethod.md @@ -8,7 +8,11 @@ description : {$methodReturnDesc}{$hasDesc} -{$methodDescription}{hasDesc$}{$hasExample} + **{$className}{$connector}{$methodName} Description** + + {$methodDescription}{hasDesc$}{$hasExample} !!! example "Example" {$methodExample}{hasExample$} + +--- diff --git a/src/Samsara/Roster/Processors/InterfaceInlineProcessor.php b/src/Samsara/Roster/Processors/InterfaceInlineProcessor.php index 0baaf13..bb6be61 100644 --- a/src/Samsara/Roster/Processors/InterfaceInlineProcessor.php +++ b/src/Samsara/Roster/Processors/InterfaceInlineProcessor.php @@ -25,6 +25,10 @@ public function compile(): string $description = (empty($this->docBlock->description) ? '*No description available*' : $this->docBlock->description); + if (TemplateFactory::getMkDocs()) { + $description = str_replace(PHP_EOL, PHP_EOL.' ', $description); + } + $this->templateProcessor->supplyReplacement('interfaceName', $this->interface->getShortName()); $this->templateProcessor->supplyReplacement('interfaceNamespace', $this->interface->getNamespaceName()); $this->templateProcessor->supplyReplacement('interfaceDesc', $description); diff --git a/src/Samsara/Roster/Processors/MethodArgumentDetailProcessor.php b/src/Samsara/Roster/Processors/MethodArgumentDetailProcessor.php index 91d4c02..930a693 100644 --- a/src/Samsara/Roster/Processors/MethodArgumentDetailProcessor.php +++ b/src/Samsara/Roster/Processors/MethodArgumentDetailProcessor.php @@ -50,6 +50,10 @@ public function compile(): string $desc = $this->tags[$tagAccessor]->description; } + if (TemplateFactory::getMkDocs()) { + $desc = str_replace(PHP_EOL, PHP_EOL.' ', $desc); + } + $template->supplyReplacement('argDesc', $desc); $argTypeDoc = ''; diff --git a/src/Samsara/Roster/Processors/MethodProcessor.php b/src/Samsara/Roster/Processors/MethodProcessor.php index f76abfd..0d662ae 100644 --- a/src/Samsara/Roster/Processors/MethodProcessor.php +++ b/src/Samsara/Roster/Processors/MethodProcessor.php @@ -52,8 +52,14 @@ public function compile(): string } if (!empty($this->docBlock->description)) { + if (TemplateFactory::getMkDocs()) { + $methodDesc = str_replace(PHP_EOL, PHP_EOL.' ', $this->docBlock->description); + } else { + $methodDesc = $this->docBlock->description; + } + $this->templateProcessor->markHas('Desc'); - $this->templateProcessor->supplyReplacement('methodDescription', $this->docBlock->description); + $this->templateProcessor->supplyReplacement('methodDescription', $methodDesc); } $returnType = (string)$this->method->getReturnType(); diff --git a/src/Samsara/Roster/Processors/TraitInlineProcessor.php b/src/Samsara/Roster/Processors/TraitInlineProcessor.php index 7ad8216..7749c5c 100644 --- a/src/Samsara/Roster/Processors/TraitInlineProcessor.php +++ b/src/Samsara/Roster/Processors/TraitInlineProcessor.php @@ -26,6 +26,10 @@ public function compile(): string $description = (empty($this->docBlock->description) ? '*No description available*' : $this->docBlock->description); + if (TemplateFactory::getMkDocs()) { + $description = str_replace(PHP_EOL, PHP_EOL.' ', $description); + } + $this->templateProcessor->supplyReplacement('traitName', $this->trait->getShortName()); $this->templateProcessor->supplyReplacement('traitNamespace', $this->trait->getNamespaceName()); $this->templateProcessor->supplyReplacement('traitDesc', $description); @@ -54,6 +58,10 @@ public function compile(): string $methodDoc = new DocBlockProcessor($method->getDocComment()); $originalMethodDesc = (empty($methodDoc->description) ? '*No description available*' : $methodDoc->description); + if (TemplateFactory::getMkDocs()) { + $originalMethodDesc = str_replace(PHP_EOL, PHP_EOL.' ', $originalMethodDesc); + } + $aliasTemplate->supplyReplacement('originalMethod', $original); $aliasTemplate->supplyReplacement('newMethod', $alias); $aliasTemplate->supplyReplacement('originalMethodDesc', $originalMethodDesc); diff --git a/src/Samsara/Roster/TemplateFactory.php b/src/Samsara/Roster/TemplateFactory.php index a90a529..dda3a87 100644 --- a/src/Samsara/Roster/TemplateFactory.php +++ b/src/Samsara/Roster/TemplateFactory.php @@ -21,6 +21,8 @@ class TemplateFactory private static array $writtenFiles = []; private static bool $preferSource = true; private static int $visibilityLevel = 1; + private static bool $mkdocs = false; + private static string $theme = 'sphinx'; public static function setPreferSource(bool $preferSource) { @@ -32,6 +34,26 @@ public static function getPreferSource(): bool return self::$preferSource; } + public static function setMkDocs(bool $mkdocs) + { + self::$mkdocs = $mkdocs; + } + + public static function getMkDocs(): bool + { + return self::$mkdocs; + } + + public static function setTheme(bool $theme) + { + self::$theme = $theme; + } + + public static function getTheme(): string + { + return self::$theme; + } + public static function setVisibilityLevel(int $visibilityLevel) { self::$visibilityLevel = $visibilityLevel;