Where communities thrive

  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
Repo info
    Sergei Vorobev
    @BernieWhite good call, I didn’t explicitly publish them before
    Bernie White
    Thoughts for where other documentation should be located that is not default repo documentation, but not cmdlet help either? Generally this be /docs/ but are we ok to mix help. Thinking of doing some more detailed examples and well need a place to extensibility documentation.
    Sergei Vorobev
    Hm good question. Would about topic in docs suite?
    Bernie White
    @vors :) yes, that would work. Can't think of any reason why it shouldn't be visible from PS.
    Sergei Vorobev
    :) it will also be a good dogfooding
    Bernie White
    @vors can you explain the purpose of the applicable metadata key/value for parameters. Struggling to understand what the use case for it is.
    Bernie White
    @vors Scratch that I found your original design issue that explains the use case. Thanks
    Sergei Vorobev
    @BernieWhite merging many versions into one
    Sorry for bad documentation around this feature
    I was trying to write a post about it but never finished
    Bernie White
    @vors Another question :) when would the scenario be used where multiple cmdlets are defined in a single .md file. We seem to allow for it in some ways but not others. e.g. How would this work with a markdown header and online version.
    Sergei Vorobev
    @BernieWhite in schema v1 we put all cmdlets for the module in a single file. That proved to be bad for multiple reasons. So now we only want 1 cmdlet per file. Places where it’s allowed for many are just historical artifacts
    Bernie White
    Bernie White
    Thanks. Slow because I haven't had too much time recently but some significate speed improvement from my baseline testing. Working through the latest merges
    Troy Lindsay
    @vors I'm stuck on #373. I can't get the YamlRenderer to not throw an error for New-YamlHelp for sections that have no content, and my New-MarkdownHelp functional tests on my own module that have these sections populated aren't populating with content. I think that the latter might be an upstream issue because the content is only showing up in a few specific use cases. Anyway, if you have time, would you take a look and see if I'm doing anything obviously wrong, please?
    Bernie White
    @tlindsay42 Haven't had enough time to look at it fully, but my first suggestion would be. What happens when Component and Functionality are null or empty, which is going to be the case 99% of the time.
    Troy Lindsay
    Thanks @BernieWhite. That was what I was trying to account for and wanted to set it to an empty string in that case. This is my first time writing anything in C#, so please forgive my ignorance if I'm missing something obvious.
    Bernie White
    @tlindsay42 I'd have a csharp unit test that tests this case, as it will be easier to debug csharp code in csharp.
    Troy Lindsay
    The existing Pester NUnit test already covers this, and here are the errors:
    New-YamlHelp ".\docs\New-YamlHelp.md" -OutputFolder ".\out\yaml" -Force
    Exception calling "MamlModelToString" with "1" argument(s): "Object reference not set to an instance of an object."
    At C:\Users\tlindsay\IDrive-Sync\git\platyPS\out\platyPS\platyPS.psm1:735 char:17
    + ...             $yaml = [Markdown.MAML.Renderer.YamlRenderer]::MamlModelT ...
    +                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : NullReferenceException
    MySetContent : Cannot bind argument to parameter 'value' because it is an empty string.
    At C:\Users\tlindsay\IDrive-Sync\git\platyPS\out\platyPS\platyPS.psm1:738 char:59
    + ...               MySetContent -Path $outputFilePath -Value $yaml -Encodi ...
    +                                                             ~~~~~
    + CategoryInfo          : InvalidData: (:) [MySetContent], ParameterBindingValidationException
    + FullyQualifiedErrorId : ParameterArgumentValidationErrorEmptyStringNotAllowed,MySetContent
    Rather, that is the error on my laptop when duplicating the scenario
    That's the error in Pester on the AppVeyor build
    Sergei Vorobev
    I agree with Bernie - it would be easier to localize the problem with csharp xunit tests
    Sergei Vorobev
    The error (NullReference) comes from yamlRenderer call. Looking at this diff
    @@ -18,9 +18,12 @@ namespace Markdown.MAML.Renderer
                 var model = new YamlCommand
                     Name = mamlCommand.Name,
    -                Notes = mamlCommand.Notes.Text,
    -                Remarks = mamlCommand.Description.Text,
    -                Summary = mamlCommand.Synopsis.Text,
    +                Component = mamlCommand.Component.Text.ToString(),
    +                Functionality = mamlCommand.Functionality.Text.ToString(),
    +                Notes = mamlCommand.Notes.Text.ToString(),
    +                Remarks = mamlCommand.Description.Text.ToString(),
    +                Role = mamlCommand.Role.Text.ToString(),
    +                Summary = mamlCommand.Synopsis.Text.ToString(),
                     Examples = mamlCommand.Examples.Select(CreateExample).ToList(),
                     Inputs = mamlCommand.Inputs.Select(CreateInputOutput).ToList(),
                     Links = mamlCommand.Links.Select(CreateLink).ToList(),
    It’s probably fair to say that the error is on one of the mamlCommand.Component or mamlCommand.Component.Text fields
    Sergei Vorobev
    It would be much easier to decode in a csharp unit test
    it could be adapted for the yaml renderer
    Bernie White
    Yes, I agree with vors and tested (works). The sections above in vors snip show the issue. Component, Functionality and Role are null unless they has a section in the source markdown. In ModelTransformerVersion2.cs::SectionDispatch creates a new SectionBody only when the header exists. So if later the Component, Functionality and Role are null you won't be able to call Text.ToString().
    In a branch I am working on I did encounter a case where .Notes might be null. So try comething like Component = mamlCommand.Component?.Text
    ToString() is no required because .Text property is already a string type. But using the null check operator ?. allows for a compact check against null for when Component, Functionality and Role are null.
    is not*
    That said, we need to have a good robust unit test that can call YamlRenderer with different objects
    Bernie White
    Good work, keep it up
    Troy Lindsay
    The null check operator was just what I was looking for! All existing automated tests are passing now. Thanks @BernieWhite & @vors! :thumbsup:
    I just have one more issue, which is that the new fields are not populating in the Markdown files in my functional tests on my laptop when there is content in the new sections. The other SectionBody properties appear to still be working properly. Any thoughts?
    Troy Lindsay
    Here's more detail on the possible upstream issue that I mentioned earlier:
    PS C:\> Get-Help -Name Connect-Armor -Functionality
    Get-Help : Missing an argument for parameter 'Functionality'. Specify a parameter of type 'System.String[]' and try again.
    At line:1 char:30
    + Get-Help -Name Connect-Armor -Functionality
    +                              ~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [Get-Help], ParameterBindingException
    + FullyQualifiedErrorId : MissingArgument,Microsoft.PowerShell.Commands.GetHelpCommand
    PS C:\> ( Get-Help -Name Connect-Armor ).Functionality
    Armor session management
    PS C:\> $help = Get-Help -Name Connect-Armor -Full; $help.Functionality
    Armor session management
    PS C:\> ( ( Get-Help -Name Connect-Armor -Full ).ToString() | Select-String -Pattern 'FUNCTIONALITY|COMPONENT' ).Count
    PS C:\> Get-Help -Name Connect-Armor -Full | Select-String -Pattern 'FUNCTIONALITY|COMPONENT'
    @{parameters=@{parameter=System.Management.Automation.PSObject[]}; inputTypes=@{inputType=@{type=@{name=None- this function does not accept pipeline inputs.}}}; returnValues=@{returnValue=@{type=@{name=ArmorSession}}};
    alertSet=@{alert=System.Management.Automation.PSObject[]}; description=System.Management.Automation.PSObject[]; details=@{name=Connect-Armor}; examples=@{example=System.Management.Automation.PSObject[]};
    relatedLinks=@{navigationLink=System.Management.Automation.PSObject[]}; syntax=@{syntaxItem=@{parameter=System.Management.Automation.PSObject[]; name=Connect-Armor}}; xmlns:maml=http://schemas.microsoft.com/maml/2004/10;
    xmlns:command=http://schemas.microsoft.com/maml/dev/command/2004/10; xmlns:dev=http://schemas.microsoft.com/maml/dev/2004/10; Name=Connect-Armor; Category=Function; Synopsis=; Component=Armor API; Role=; Functionality=Armor session management; ModuleName=Armor}
    Oh nm. Just saw your updates on issue #373
    Hey everyone, got a question. Anyone integrated PlatyPS into an Azure DevOps pipeline to update Wiki content?
    Joey Piccola
    Hello, struggling a bit with Update-MarkdownHelpModule. Have my module imported, but the markdown docs are not being updated. -verbose indicates 'because content is not changing.' However, when doing a get help on a function in my loaded module I clearly see a description that is different than what is in my markdown file.
    the description is what has been updated and what I am trying to get updated in my markdown files. thanks!
    Mike Veazie
    Hey, is this still active?

    I am wondering if it there is an existing option for excluding parameters that do not have values:

    external help file: Hello.World-help.xml
    Module Name: Hello.World
    online version:
    schema: 2.0.0
    # Get-HelloWorld
    This is an example markdown help file
    ## SYNTAX


    {{ Fill in the Description }}
    ### Example 1
    PS C:\> {{ Add example code here }}

    {{ Add example description here }}







    When you run New-MarkdownHelp, it generates headings for help areas I do not want to add. Is there a way to suppress this already?
    Sean Wheeler
    We are in the process of making major changes to platyPS. But there is a schema that this required by our publishing system. So those headings are required. Also, platyPS expects those heading when it creates the MAML files.
    Nick Spreitzer
    @sdwheeler I'm curious if you can share a time frame for when we might see these upcoming changes?
    Kirill Nikolaev
    Hi guys! I have a module where I use custom enums and classes in parameters. The module works just fine, but when I try to generate markdown help for it, PlatyPS seems to have no idea about those custom classes and enums, unless I explicitly import them into the current PowerShell session. Is it normal or am I doing something wrong?
    Nick Spreitzer
    That's normal.