Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    Sergei Vorobev
    @vors
    @BernieWhite good call, I didn’t explicitly publish them before
    fixed
    Bernie White
    @BernieWhite
    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
    @vors
    Hm good question. Would about topic in docs suite?
    Bernie White
    @BernieWhite
    @vors :) yes, that would work. Can't think of any reason why it shouldn't be visible from PS.
    Sergei Vorobev
    @vors
    :) it will also be a good dogfooding
    Bernie White
    @BernieWhite
    @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
    @BernieWhite
    @vors Scratch that I found your original design issue that explains the use case. Thanks
    Sergei Vorobev
    @vors
    @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
    @BernieWhite
    @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
    @vors
    @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
    @BernieWhite
    Thanks
    Bernie White
    @BernieWhite
    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
    @tlindsay42
    @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
    @BernieWhite
    @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
    @tlindsay42
    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
    @BernieWhite
    @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
    @tlindsay42
    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
    image.png
    That's the error in Pester on the AppVeyor build
    Sergei Vorobev
    @vors
    I agree with Bernie - it would be easier to localize the problem with csharp xunit tests
    Sergei Vorobev
    @vors
    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
    @vors
    It would be much easier to decode in a csharp unit test
    it could be adapted for the yaml renderer
    Bernie White
    @BernieWhite
    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
    @BernieWhite
    Good work, keep it up
    Troy Lindsay
    @tlindsay42
    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
    @tlindsay42
    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
    0
    
    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
    jacorbello
    @jacorbello
    Hey everyone, got a question. Anyone integrated PlatyPS into an Azure DevOps pipeline to update Wiki content?
    Joey Piccola
    @joeypiccola
    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
    @easyveazie
    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
    
    ## SYNOPSIS
    This is an example markdown help file
    
    ## SYNTAX

    Get-HelloWorld

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

    {{ Add example description here }}

    PARAMETERS

    INPUTS

    OUTPUTS

    NOTES

    RELATED LINKS

    ```

    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
    @sdwheeler
    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
    @refactorsaurusrex
    @sdwheeler I'm curious if you can share a time frame for when we might see these upcoming changes?
    Kirill Nikolaev
    @exchange12rocks
    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
    @refactorsaurusrex
    That's normal.