Migrate Documentation to Markdown and External Help

AtlassianPS / BitbucketPS

PowerShell module to interact with Atlassian Bitbucket

https://AtlassianPS.org/BitbucketPS

MIT License

33 stars 15 forks source link

Migrate Documentation to Markdown and External Help #1

Open lipkau opened 7 years ago

lipkau commented 7 years ago

Description

In order to have a documentation that is easier to access, easier to edit and maintain, and more flexible, we shall use PlatyPS for the help of the function. Discussion on this topic: https://github.com/AtlassianPS/AtlassianPS/issues/1

Task

[ ] Migrate all Comment Based Help to .md files in /docs

Import-Module MyAwesomeModule
New-MarkdownHelp -Module MyAwesomeModule -OutputFolder .\docs

[ ] Edit the .md files (.EXAMPLE block can have more that 1 command in it)

[ ] Create the about_<module>

New-MarkdownAboutHelp -OutputFolder C:\Test -AboutName

[ ] Make AppVeyor generate the ExternalHelp file (.xml) when building
```
New-ExternalHelp -Path ".\docs" -OutputPath "out\platyPS\en-US"
```
[ ] Remove the Comment Based Help from all functions in the module

martin9700 commented 6 years ago

I'd still recommend minimal comment based help. SYNOPSIS and LINK would probably be best. That way if I do Get-Help Get-Branch -Online I'd be sent to the online help page.

lipkau commented 6 years ago

disagree. An user should be able to get basic help (including samples) from help <My-Command>. Further: the online help would not be aligned to the version the user has installed. So maybe a parameter was added, which he cannot use without updating (which will not be specified in the online help).

The online help will indeed show the latest version of the documentation of the function. but it will not be versioned.

An argument can be made, that generating an online .cab file with the help, which the user can get for local usage with Update-Help. This would allow the module to deploy fixes to the help without requiring a new release. However, this would also require the module to be smart enough to know what help .cab file to deploy the what version of the module.

ConfluencePS has already done this. all documentation is in the /docs directory as .md files. This allows the online help to be published as: https://atlassianps.org/docs/ConfluencePS/ https://atlassianps.org/docs/ConfluencePS/commands/Add-Label/

martin9700 commented 6 years ago

Oh good! I actually prefer full comment based help, but I thought the issue was to move AWAY from that to markdown. I assume the cbh will be pulled out at CI/CD?

lipkau commented 6 years ago

No. this moves away from CBH. and uses External Help instead...

basically, the help engine parses the comments for the CBH. this is very flawed; and used as a simple way to get help for cmdlets... for more sophisticated help, you need to provide an external help... this can be:

a xml file in the /en-US folder
a cab file (which I have no experiance with)

pros and cons are here: https://github.com/AtlassianPS/AtlassianPS/issues/1

martin9700 commented 6 years ago

Lol, I don't think that's the right link ;)

lipkau commented 6 years ago

fixed