msorens / doctreegenerator Goto Github PK

Regular parameters are all emboldened in the Parameters section. The final one (added automatically), "", is not. Need to add support to the recognizer for that.

Basic HTML returns unclear errors:
** Cannot convert value "System.Object[]" to type "System.Xml.XmlDocument". Error: "'"' is an unexpected token. Expecting white space. Line 1, position 63."

This goes for all overview files.

If multiple namespaces are specified for the Namespaces parameter, the page title for the home and contents pages is just the DocTitle parameter (or default). But if there is only a single namespace specified, the page title is that single namespace concatenated with the DocTitle parameter (or default). This determination is made on the literal Namespaces value passed in, even if it contains globbing wildcards and thus might resolve to multiple namespaces.

While technically that approach is valid, it would be more natural that the following two commands produce the same behavior:

PS> Convert-HelpToHtmlTree -Namespaces ns1, ns2
PS> Convert-HelpToHtmlTree -Namespaces ns*

Which is to say, to determine that multiple namespaces have been specified.

When a module defines the DefaultCommandPrefix property in its manifest, DTG can't properly locate/inspect help details of the functions (cmdlets) exported from the module.

I've verified this is true for both binary and script modules.

While trying out DocTreeGenerator, I seem to have found a problem:
DocTreeGenerator imports all modules before extracting documentation from each module. If two modules both contain a function having the same name, only the function from the last module imported is seen by DocTreeGenerator. Message displayed:

** No functions found in ModuleA-v1; (typically this means your functions or cmdlets are not exported)

In the situation above, I had a ModuleA-v2 containing all the same functions as ModuleA-v1.
This case simulates two versions of the same module.

Even if not handling module versions, it is not unlikely for two modules to contain functions having the same name.

Would it be possible to publish DocTreeGenerator to the PS Gallery? That would make the tool much more accessible in the PowerShell way.

Currently any modules to be documented, quoting the documentation "must be installed as user modules (i.e. in C:\Users\username\Documents\WindowsPowerShell\Modules) rather than system modules (i.e. C:\Windows\System32\WindowsPowerShell\v1.0\Modules)." This also means that DocTreeGenerator does not support an arbitrary directory location. Would be useful to add a -Path parameter to allow an arbitrary location.

Examples don't get properly indented even after applying one of the workarounds mentioned in README.md. We've found a fix for this in DocTreeGenerator source.

We need to add the following two lines on line 847 in Convert-HelpToHtmlTree.ps1

/cc @prithvibv

An example typically consists a single line of code (or multiple lines with backticks), followed by a description. There is one or more issues with incorrect rendering that may or may not all stem from the same cause:
A. A preformatted block immediately following the line of code has the first line incorrectly rendered as standard text. The second and subsequent lines are then rendered correctly as a pref-formatted block.
B. Backticks to continue the line of code are not being honored, so the continued lines are incorrectly rendered as plain text instead of stylized to be code.
C. Also with backticks, sometimes the first bit of code is incorrectly rendered as plain text, then the continued line rendered as preformatted text.

One is supposed to be able to introduce a link (.LINK) for either standard PowerShell cmdlets, standard PowerShell topics, or one's own custom functions. The documentation generator correctly recognizes standard items, and links to custom functions in the same module, but it fails on custom functions in a different module. Thus, such an item is just rendered as plain text, with no hyperlink.

Cause: When each module is processed it is loaded, then processed, then unloaded. Thus, its functions are not known when some other module tries to create a link.