[WIP] #152: Website for hosted documentation

[Tiberriver256]

This is just a first crack at a simple site for Polaris. We can fine tune a little bit on how we want to present the help information and add a little bit extra where it's useful.

Two big things I would love to accomplish here is

• How to keep this up-to-date with the changes being made on the master branch using the appveyor build process.
• Make sure the styling and such is acceptable

Once we get those two things out of the way we can really just focus on creating excellent documentation using comment based documentation or about_ files in the main repository and we won't have to worry about keeping the site up-to-date.

Notes on the build process

The site currently has two requirements for help files as markdown:

1. Every file has to have layout, title, and type set in the metadata. Type can be set to either api or about. layout should always be set to default since we didn't need to get fancy.

The type determines where the file will go in the navigation. A type of api gets put into the API Documentation section of the navigation and a type of about gets put into the About Guides section of the navigation.

2. The files have to be somewhere in the gh-pages branch of the repository. My proposal is to mimic the same documentation folder structure as we have in master and just keep everything in the docs folder to keep things clear and also make the build process easier.

This looks like a lot but we can achieve all of that for the API documentation using platyPS and the -Metadata parameter like this:

Get-Command -Module Polaris | foreach { 
New-MarkdownHelp -Command $_ -OnlineVersionUrl "https://powershell.github.io/Polaris/docs/$($_.Name).html" -Metadata @{layout="default";title=$_.Name;type="api"
} -OutputFolder .\docs\api -Force  }

That will auto-generate all of our markdown files for api from comment-based help with the necessary metadata in the header.

For writing about_ files we want to include with the module we can write them following platyPS standards just adding the required metadata fields at the top. i.e.

---
layout: default
title: About Polaris
type: about
---

# Polaris

## about_Polaris

. . .

If we can get that command into our standard build process and we could set up git push to allow pushing back into the gh-pages branch from appveyor. We could do the following steps during an automated release:

1. Regenerate the API documentation using the above command
2. Copy the docs folder to somewhere outside the checked out repo
3. Checkout the gh-pages branch
4. Copy the docs folder back in replacing everything that's existing
5. Push all changes back up to gh-pages

Phew... that was a lot... lol. Let me know what you think or if you have a simpler solution or would rather not tackle all of that in one PR.

Related issue #152

[TylerLeonhardt]

Sorry I took so long to see this!

This looks great. I think if we can just write a quick script that will do the git-push, I can make sure it gets run on releases. :)

[TylerLeonhardt]

this?

$tempPath = Join-Path ([System.IO.Path]::GetTempPath()) polaris_api_docs
Get-Command -Module Polaris | foreach { 
    New-MarkdownHelp -Command $_ -OnlineVersionUrl "https://powershell.github.io/Polaris/docs/$($_.Name).html" -Metadata @{layout="default";title=$_.Name;type="api" } -OutputFolder $tempPath -Force
}
git checkout gh-pages
Copy-Item -Recurse -Force $tempPath docs/api
git push origin gh-pages

[Tiberriver256]

Looks like that should work to me! Freaking sweet man thanks!

…

On Fri, Nov 16, 2018, 8:30 PM Tyler James Leonhardt < ***@***.***> wrote: this? $tempPath = Join-Path ([System.IO.Path]::GetTempPath()) polaris_api_docsGet-Command -Module Polaris | foreach { New-MarkdownHelp -Command $_ -OnlineVersionUrl "https://powershell.github.io/Polaris/docs/$($_.Name).html" -Metadata @{layout="default";title=$_.Name;type="api" } -OutputFolder $tempPath -Force } git checkout gh-pagesCopy-Item -Recurse -Force $tempPath docs/api git push origin gh-pages — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#159 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AGqmtHDC5I5sJY7YxFqIMW8K6jKJDiq9ks5uv2aggaJpZM4YYTZw> .

[TylerLeonhardt]

LGTM! I don't think there's anything else to address. Do you @Tiberriver256?

[Tiberriver256]

Sweet nope! We can merge away and I can get started on writing some about_ files.