Write docs outside of artifacts directory

[Dan Tsekhanskiy]

Description

While generating docs, it looks like Catesta only writes documentation generated by platyPS to the artifacts folder. I'm not sure if this is WAI, but it would be useful to generate docs in the root directory (I'll leave the actual location up to you). Having docs in the root directory would make them more discoverable when someone is browsing a git repo, as they're immediately visible. Currently, docs are not automatically written to any directory that's uploaded to GitHub.

Describe the solution you'd like

When the CreateMarkdownHelp task executes, docs are written to the root directory (alongside src, media, .vscode, etc.). Whether they also need to live in the artifacts dir, I'll leave up to you.

Describe any alternatives you've considered

A scripted copy of the docs generated and written to the artifacts directory would be possible, to avoid unnecessary calls to platyPS and ensure the docs are always the same between the two directories.

Additional context

I've manually copied the docs for now, but I'd like to hear your thoughts on how to address this.

[Dan Tsekhanskiy]

Noticing that you have code to do this already:

    # here you could move your docs up to your repos doc level if you wanted
    Write-Build Gray '        Overwriting docs output...'
    Move-Item "$($script:ArtifactsPath)\docs\*.md" -Destination "..\docs\" -Force
    Remove-Item "$($script:ArtifactsPath)\docs" -Recurse -Force -ErrorAction Stop
    Write-Build Gray '        ...Docs output completed.'

This seems to be commented out in the module available from PSGallery. Assuming something wasn't working here and thus this was commented out, and the changes in this repo haven't been pushed to PSGallery just yet?

[Jake Morrison]

This is functional code, and can be un-commented and utilized.

This was commented out because some module authors opt to reverse their help workflow once the markdown is published.

Initial help based comments -> Markdown generated -> External help generated -> Comment based help replaced with external help reference.

At this point some module authors stop updating comment based help and elect instead to edit the markdown directly and then regen from that point using platyPS directly.

Module generators by their nature are somewhat opinionated and I hadn't made a decision if replacing the top level docs on each build was the right call.

Thus, this was commented out.

In review, I think Catesta is driven from a design model that derives the 'source of help truth' from the comment based help. So, I will get this un-commented and documented as the default behavior.

[Dan Tsekhanskiy]

Sounds reasonable, thanks for the context!