updating comment based help and platyPS tasks to run out of process (…

gaelcolas commented 3 years ago

Thanks to @pshamus

Here's the draft I'm working on.

I'm not sure about the workflow yet:

if we have Comment based help, what should we do?
- Generate markdown help files in Source?
- Generate the markdown help files in output and build Maml from there (it won't be clean)
if we only have Markdown help, just generate the Maml and ship it in en-US or whatever folder?

Let me knwo how you see the workflow so I can finish this up.

This change is

gaelcolas commented 3 years ago

So I've created 3 tasks:

Generate_maml_from_built_module
update_markdown_help_source
Generate_MAML_From_Markdown_help_source

_NOTES: Make sure you understand help priorities between Comment based help, Help file, and what you need to change, because this module is not updating the comment-based help for you (i.e. # .ExternalHelp entry). That means 'Generate_maml_from_builtmodule' is probably not really usable yet. (this is still a draft, afterall)

from the doc: Note that the .EXTERNALHELP keyword takes precedence over all other comment-based help keywords. When .EXTERNALHELP is present, the Microsoft.PowerShell.Commands.GetHelpCommand cmdlet does not display comment-based help, even when it cannot find a help file that matches the value of the keyword.

Generate_maml_from_built_module

This task is used to take the current Comment Based help (CBH) from the module, and generate a MAML help file based on this info. The process will first convert the CBH to Markdown. Then from Markdown to MAML. Because you can't check the Markdown or MAML and it's likely to loose some formatting, that's not the best workflow (it's done at build time in the output). However, that means we can build a MAML and make it available outside of a Module release (say if you branch out a tag just to update the help).

update_markdown_help_source

This task is used to either generate or update the Markdown help source files (by default in the 'docs/' folder, at the Project's root).

This task can be used during the Dev workflow when a function has had a parameter added. The task will look for the Markdown file (For every locale that exists under docs/ and will update it without changing the rest of the document. Bear in mind that if the parameter description is in English, it will still use the same content for each Locale/CultureInfo.

Generate_MAML_From_Markdown_help_source

When the source is up to date, it can be used to generate the MAML file (for each locale/CultureInfo).

This will look into docs/ for the source markdown and create the MAML files in the output/help folder, with a version subfolder and locale subfolders:

SAMPLER\OUTPUT\HELP
└───0.109.10-preview0001
    ├───en-US
    │       Sampler-help.xml
    │
    └───fr-FR
            Sampler-help.xml

Those will also be copied (by default) to the built module folder (i.e. SAMPLER\OUTPUT\SAMPLER\0.109.10\en-US\Sampler-help.xml).

I have not yet parameterized some of the options for the PlatyPS commands, hence why it's still a draft. I'm also looking at how to enable updated help, when we have CBH (i.e. automatically adding .EXTERNALHELP at compile time).

Let me know your thoughts.

pshamus commented 3 years ago

Other than inconsistent case of the task names, all those sound good. For Generate_MAML_From_Markdown_help_source, what's the reasoning behind generating the help in output\help rather than just putting it in the built module?

gaelcolas commented 3 years ago

generating in output/help to make the MAML available (say you want to publish in CAB or make available separately). There's a copy to Built Module Base by default, so it will be available there anyway too.

We can't directly put it to BuiltModuleBase because then it might be "harder" to get it from there (exact path, is there some other files like *.strings.psd1, maybe we have a Locale folder without MAML...).

pshamus commented 3 years ago

Gotcha, makes total sense. Thanks!

johlju commented 3 years ago

@gaelcolas

I'm also looking at how to enable updated help, when we have CBH (i.e. automatically adding .EXTERNALHELP at compile time).

Could we use ScriptAnalyzer "Fix" functionality by adding a custom rule that supports adding (fixing) this? 🤔 I just saw the other day Chris mentioned that "Fix" triggers a method or function (don't remember), but worth checking out. If I'm not misunderstand what you meant. 🙂

gaelcolas commented 3 years ago

Yeah, I'm not convinced for source/docs vs docs. For instance, tests is not under source yet it should trigger a pipeline if changed (but not a module release). Same goes for docs, maybe we should be able to update the docs/help/maml without the need to release a new module. And maybe the docs folder has more than the commands? Maybe detailed explanation on how to contribute to the project (linked from contributing.md). In that case you may not want to hide it under source... And the what do we do with wikisource, is it the same? Different?

johlju commented 3 years ago

When tests are update they are verified to run in the PR so they don't need to run when merged to default branch.

We could say that since docs should not be updated manually it should not be in source, and say that any docs that should be update manually and is published to one or more sources should be in source folder. But there is no reason to merge docs that are updated automatically in the repo. It can be built on each run.

What is the reason for merging it after it been built?

johlju commented 3 years ago

Btw. it looks like the tasks work in my quick test. But why is the docs generated both to /output folder and to /docs folder? 🤔 Isn't output folder enough for it to be published or added to the release?

gaelcolas commented 3 years ago

Different tasks for different use case, that's what I explained in the comment above https://github.com/gaelcolas/Sampler/pull/260#issuecomment-805855252

gaelcolas commented 3 years ago

I'll merge this when test passes and add configuration option in build.yaml in another PR.

gaelcolas / Sampler