+ {{^_disableToc}} + {{>partials/toc}} +
+ {{/_disableToc}} + {{#_disableToc}} +
+ {{/_disableToc}} + {{#_disableAffix}} +
+ {{/_disableAffix}} + {{^_disableAffix}} +
+ {{/_disableAffix}} + +
+ {{^_disableAffix}} + {{>partials/affix}} + {{/_disableAffix}} +
+
+ {{^_disableFooter}} + {{>partials/footer}} + {{/_disableFooter}} +
+ {{>partials/scripts}} + + diff --git a/docs/template/partials/class.tmpl.partial b/docs/template/partials/class.tmpl.partial new file mode 100644 index 000000000..c898239f6 --- /dev/null +++ b/docs/template/partials/class.tmpl.partial @@ -0,0 +1,135 @@ +{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} + +{{^_disableContribution}} +{{#docurl}}{{__global.improveThisDoc}}{{/docurl}} +{{#sourceurl}}{{__global.viewSource}}{{/sourceurl}} +{{/_disableContribution}} +

{{>partials/title}}

+
{{{summary}}}
+
{{{conceptual}}}
+{{#inheritance.0}} +
+
{{__global.inheritance}}
+{{#inheritance}} +
{{{specName.0.value}}}
+{{/inheritance}} +
{{item.name.0.value}}
+
+{{/inheritance.0}} +
{{__global.namespace}}:{{namespace}}
+
{{__global.assembly}}:{{assemblies.0}}.dll
+
{{__global.syntax}}
+
+ 
{{syntax.content.0.value}}
+
+{{#remarks}} +
{{__global.remarks}}
+
{{{remarks}}}
+{{/remarks}} +{{#children}} +

{{>partials/classSubtitle}}

+{{#children}} +{{^_disableContribution}} +{{#docurl}} + + | + {{__global.improveThisDoc}} +{{/docurl}} +{{#sourceurl}} + + {{__global.viewSource}} +{{/sourceurl}} +{{/_disableContribution}} +

{{name.0.value}}

+
{{{summary}}}
+
{{{conceptual}}}
+{{#remarks}} +
{{__global.remarks}}
+
{{{remarks}}}
+{{/remarks}} +
{{__global.declaration}}
+{{#syntax}} +
+ 
{{syntax.content.0.value}}
+
+{{#parameters.0}} +
{{__global.parameters}}
+ + + + + + + + + +{{/parameters.0}} +{{#parameters}} + + + + + + {{/parameters}} + {{#parameters.0}} + +
{{__global.type}}{{__global.name}}{{__global.description}}
{{{type.specName.0.value}}}{{{id}}}{{{description}}}
+{{/parameters.0}} +{{#return}} +
{{__global.returns}}
+ + + + + + + + + + + + + +
{{__global.type}}{{__global.description}}
{{{type.specName.0.value}}}{{{description}}}
+{{/return}} +{{#propertyValue}} +
{{__global.provertyValue}}
+ + + + + + + + + + + + + +
{{__global.type}}{{__global.description}}
{{{type.specName.0.value}}}{{{description}}}
+{{/propertyValue}} +{{/syntax}} +{{#exceptions.0}} +
{{__global.exceptions}}
+ + + + + + + + +{{/exceptions.0}} +{{#exceptions}} + + + + +{{/exceptions}} +{{#exceptions.0}} + +
{{__global.type}}{{__global.condition}}
{{{type.specName.0.value}}}{{{description}}}
+{{/exceptions.0}} +{{/children}} +{{/children}} diff --git a/docs/template/partials/footer.tmpl.partial b/docs/template/partials/footer.tmpl.partial new file mode 100644 index 000000000..47254342c --- /dev/null +++ b/docs/template/partials/footer.tmpl.partial @@ -0,0 +1,7 @@ +{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} + +
+
+

© Microsoft  //  Generated with DocFX

+
+
diff --git a/docs/template/partials/head.tmpl.partial b/docs/template/partials/head.tmpl.partial new file mode 100644 index 000000000..95c6b4424 --- /dev/null +++ b/docs/template/partials/head.tmpl.partial @@ -0,0 +1,28 @@ +{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} + + + + + {{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}} + + + {{#_description}}{{/_description}} + + + + + + + + + \ No newline at end of file diff --git a/docs/template/partials/namespace.tmpl.partial b/docs/template/partials/namespace.tmpl.partial new file mode 100644 index 000000000..1147b2278 --- /dev/null +++ b/docs/template/partials/namespace.tmpl.partial @@ -0,0 +1,21 @@ +{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} + +{{^_disableContribution}} +{{#docurl}} +{{__global.improveThisDoc}} +{{/docurl}} +{{#sourceurl}} +{{__global.viewSource}} +{{/sourceurl}} +{{/_disableContribution}} +

{{>partials/title}}

+
{{{summary}}}
+
{{{conceptual}}}
+
{{{remarks}}}
+{{#children}} +

{{>partials/namespaceSubtitle}}

+ {{#children}} +

{{{specName.0.value}}}

+
{{{summary}}}
+ {{/children}} +{{/children}} diff --git a/docs/template/partials/navbar.tmpl.partial b/docs/template/partials/navbar.tmpl.partial new file mode 100644 index 000000000..0b1663b50 --- /dev/null +++ b/docs/template/partials/navbar.tmpl.partial @@ -0,0 +1,18 @@ +{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} + + diff --git a/docs/template/styles/main.css b/docs/template/styles/main.css new file mode 100644 index 000000000..f9c1549f5 --- /dev/null +++ b/docs/template/styles/main.css @@ -0,0 +1,268 @@ +@import url(//fonts.googleapis.com/css?family=Roboto+Condensed:700); +@import url(//fonts.googleapis.com/css?family=Open+Sans); + +/* Main styles */ +body { + font-family: "Open Sans", "Segoe UI", sans-serif; + font-size: 15px; + padding-top: 50px; +} +ul { + list-style-image: url("../../images/core/list-bullet.png"); +} +nav { + font-size: 14px; +} +.navbar-nav > li > a.nav-active, .navbar-nav > li > a.nav-active:hover { + background-color: #333; + color: #fff; +} + +h1, h2, h3, h4, h5 { + font-family: "Roboto Condensed", "Segoe UI", sans-serif; + font-weight: bold; +} + + +footer { + text-align: center; + width: 100%; + margin-top: 50px; + color: #c0c0c0; +} +footer > .inner-footer a { + color: #c0c0c0; + text-decoration: none; +} +footer > .inner-footer a:hover { + color: #32145a; + text-decoration: none; +} +.content a { + /*color: #A979B3;*/ + color: #A356B3; + text-decoration: none; + outline: 0; +} +.content a:hover { + /*transition: color .15s cubic-bezier(.33, .66, .66, 1);*/ + text-decoration: none; + color: #682079; +} + + +/* End of main styles */ + +/* Index page styles */ +.btn-hero-core { + padding: 15px 25px; + background-color: #32145a; + color: #d89ae4; + display: inline-block; + font-family: "Open Sans", sans-serif; + font-size: 20px; + font-weight: bold; + margin-left: 20px; + -webkit-box-shadow: 2px 2px 3px 0px #2C0D33; /* Safari 3-4, iOS 4.0.2 - 4.2, Android 2.3+ */ + -moz-box-shadow: 2px 2px 3px 0px #2C0D33; /* Firefox 3.5 - 3.6 */ + box-shadow: 2px 2px 3px 0px #2C0D33; /* Opera 10.5, IE 9, Firefox 4+, Chrome 6+, iOS 5 */ +} +.btn-hero-core:hover { + color: #d89ae4; + text-decoration: none; +} +.hero { + background-color: #682079; + width: inherit; + color: #fff; +} +.starter-template { + padding: 40px 15px; + text-align: center; +} +.dotnet { + color: #fff; +} +#rest-vps { + display: none; +} +.value-prop-heading { + margin-top: 0px; +} +.value-props { + margin-top: 40px; + margin-bottom: 40px; +} + +.intro-image { + text-align: center; +} +.intro-image > img { + margin-top: 20px; +} + +/* End of index page styles */ + +/* Getting started page styles */ +.getting-started-intro { + text-align: center; + margin-top: 40px; + margin-bottom: 40px; +} +.getting-started-intro > h2, h4 { + margin-bottom: 30px; +} +.btn-gs { + width: 150px; +} +.btn-gs:hover, .btn-gs:active, .btn-gs:focus, .jquery-active { + color: #fff; + background-color: #682079; + outline: 0 !important; +} + + +.step { + width: 100%; + margin: 50px auto; + padding: 20px 0px; + text-align: center; + font-size: 16px; + border: solid 1px #c0c0c0; + min-height: 300px; + background-color: #fff; + border-radius: 10px; +} +.step-block { + display: block; +} +.step-none { + display: none; +} +.step-number { + position: relative; + top: -40px; + background-color: #32145a; + color: #fff; + font-weight: bold; + font-size: 24px; + z-index: 999; + margin-left: auto; + margin-right: auto; + width: 80px; + padding: 10px; + border: solid 1px #c0c0c0; + border-radius: 10px; +} + +.step > h3 { + margin: 0; + margin-bottom: 30px; + font-size: 30px; +} +.step > p { + margin-top: 10px; + margin-bottom: 20px; + width: 70%; + text-align: center; + margin-left: auto; + margin-right: auto; +} +.code-sample { + white-space: pre; +} + + +/* Terminal backgrounds */ +.terminal { + display: block; + width: 850px; + margin-left: auto; + margin-right: auto; +} +.terminal-titlebar { + background-color: #c0c0c0; + height: 30px; + border-top-left-radius: 5px; + border-top-right-radius: 5px; +} + +.terminal-body { + background-color: #000; + color: #fff; + font-family: "Consolas", "Monaco", monospace; + font-size: 16px; + font-weight: bold; + padding: 15px; + text-align: left; + height: auto; + overflow: auto; + word-wrap: break-word; + border-bottom-left-radius: 5px; + border-bottom-right-radius: 5px; +} +.prompt { + -webkit-touch-callout: none; + -webkit-user-select: none; + -khtml-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; + color: #c0c0c0; +} +.windows-prompt:after { + content: 'PS > '; +} +.unix-prompt:after { + content: '~$ '; +} + +@media (max-device-width: 480px) and (orientation: portrait), (max-device-width: 700px) and (orientation: landscape){ + /* Index page overrides */ + .btn-hero-core { + padding: 10px 15px; + margin-left: 0px; + font-size: 16px; + } + .intro-image > img { + display: none; + } + + /* Overview overrides */ + img[src*="10kft_view"] { + width: 100%; + height: 100%; + } + + /* Getting started overrides */ + .btn-gs { + width: auto; + } + + .btn-gs:hover, .btn-gs:active, .btn-gs:focus, .jquery-active { + width: auto; + } + + .step { + width: 90%; + font-size: 14px; + } + .step > h3 { + font-size: 24px; + } + .step-number { + width: 40px; + font-size: 18px; + padding: 5px; + } + .terminal { + width: 95%; + } + .terminal-titlebar { + height: 20px; + } + .terminal-body { + font-size: 12px; + padding: 5px; + } +} diff --git a/docs/template/styles/style.css b/docs/template/styles/style.css new file mode 100644 index 000000000..2fd826e1d --- /dev/null +++ b/docs/template/styles/style.css @@ -0,0 +1,43 @@ +body { + font-family: "Open Sans", "Segoe UI", sans-serif; + padding-top: 0px; +} +footer { + z-index: 0; +} +.navbar-brand { + font-size: 18px; + padding: 15px; +} +.toc .level3 { + font-weight: normal; + margin-top: 5px; + margin-left: 10px; +} +a.pull-right { + margin-left: 10px; + padding-top: 5px; +} +article.content > h1 { + word-break: break-word; +} +@media only screen and (max-width: 768px) { + .toc .level3 > li { + display: inline-block; + } + .toc .level3 > li:after { + margin-left: -3px; + margin-right: 5px; + content: ", "; + color: #666666; + } +} +@media (max-width: 260px) { + .toc .level3 > li { + display: block; + } + + .toc .level3 > li:after { + display: none; + } +} diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 000000000..01f0d406e --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,5 @@ +- name: User Guide + href: guide/ + homepage: guide/introduction.md +- name: API Reference + href: api/ diff --git a/docs/using_the_dotnet_api.md b/docs/using_the_dotnet_api.md deleted file mode 100644 index 4d3da4669..000000000 --- a/docs/using_the_dotnet_api.md +++ /dev/null @@ -1,3 +0,0 @@ -# Using the PowerShell Editor Services .NET API - -**TODO:** Provide conceptual overview and code examples. \ No newline at end of file diff --git a/scripts/BuildDocs.ps1 b/scripts/BuildDocs.ps1 new file mode 100644 index 000000000..891861d07 --- /dev/null +++ b/scripts/BuildDocs.ps1 @@ -0,0 +1,73 @@ +param([switch]$Serve, [switch]$Clean, [switch]$Publish) + +$toolsPath = [System.IO.Path]::GetFullPath("$PSScriptRoot\..\tools") +$docfxZipPath = [System.IO.Path]::GetFullPath("$toolsPath\docfx.zip") +$docfxBinPath = [System.IO.Path]::GetFullPath("$toolsPath\docfx\") +$docfxExePath = [System.IO.Path]::GetFullPath("$docfxBinPath\docfx.exe") +$docfxJsonPath = [System.IO.Path]::GetFullPath("$PSScriptRoot\..\docs\docfx.json") +$sitePath = [System.IO.Path]::GetFullPath("$PSScriptRoot\..\docs\_site") +$docsRepoPath = [System.IO.Path]::GetFullPath("$PSScriptRoot\..\docs\_repo") + +# Ensure the tools path exists +mkdir $toolsPath -Force | Out-Null + +if (![System.IO.File]::Exists($docfxExePath)) { + # Download DocFX + Remove-Item -Path "$docfxBinPath" -Force -ErrorAction Stop | Out-Null + (new-object net.webclient).DownloadFile('https://github.com/dotnet/docfx/releases/download/v1.8/docfx.zip', "$docfxZipPath") + + # Extract the archive + Expand-Archive $docfxZipPath -DestinationPath $docfxBinPath -Force -ErrorAction "Stop" +} + +# Clean the _site folder if necessary +if ($Clean.IsPresent) { + Remove-Item -Path $sitePath -Force -Recurse | Out-Null +} + +# Build the metadata for the C# API +& $docfxExePath metadata $docfxJsonPath + +if ($Serve.IsPresent) { + & $docfxExePath build $docfxJsonPath --serve +} +else { + & $docfxExePath build $docfxJsonPath + + if ($Publish.IsPresent) { + # Delete the existing docs repo folder + Remove-Item -Path $docsRepoPath -Recurse -Force -ErrorAction Stop | Out-Null + + # Clone the documentation site branch of the Editor Services repo + git clone -b gh-pages https://github.com/PowerShell/PowerShellEditorServices.git $docsRepoPath + + # Copy the site files into the repo path + Write-Host -ForegroundColor Green "*** Copying documentation site files ***" + Copy-Item -Recurse -Force $sitePath\* $docsRepoPath + + # Enter the repo path and commit the changes + Write-Host -ForegroundColor Green "*** Committing changes ***" + Push-Location $docsRepoPath + git add -A + git commit -m "Updated documentation site" + + # Verify that we're ready to push and then do it + $response = + $host.ui.PromptForChoice( + "Ready to push?", + "Are you ready to push the doc site changes?", + [System.Management.Automation.Host.ChoiceDescription[]]( + (New-Object System.Management.Automation.Host.ChoiceDescription "&Yes","Yes"), + (New-Object System.Management.Automation.Host.ChoiceDescription "&No","No") + ), + 1); + + if ($response -eq 0) { + Write-Host -ForegroundColor Green "*** Pushing changes ***" + git push origin gh-pages + } + else { + Write-Output "Did not push changes. Run 'git push origin gh-pages' manually when ready." + } + } +}