Code Monkey home page Code Monkey logo

doctreegenerator's Introduction

DocTreeGenerator

PowerShell's Get-Help gives you documentation for one cmdlet at a time but it does not provide any means to document your API in its entirety. DocTreeGenerator fills that niche. Once you have instrumented your modules with doc-comments to satisfy Get-Help, you need surprisingly little extra work for DocTreeGenerator to produce a comprehensive, hyperlinked documentation tree (in the form of a collection of web pages).

When you create your library code, whether it is in PowerShell or in C#, you need to add documentation comments (doc-comments for short) that may then be automatically extracted and formatted to generate some documentation. If you are writing in PowerShell, those doc-comments are processed directly by PowerShell when you invoke Get-Help on your cmdlet. If you are writing in C#, you need to use a third party tool to pre-process your doc-comments into a form that Get-Help can use--I highly recommend XmlDoc2CmdletDoc for this purpose. It reduces what used to be a tedious and difficult task of documenting C# cmdlet libraries to the same effort needed for documenting PowerShell cmdlets--just add appropriate doc-comments in your C# code.

Beyond those standard doc-comments instrumenting your code, for DocTreeGenerator to do its job you need to provide just a few summary files as well and perhaps tweak the HTML or CSS in the template to get the look and feel you want.

To start with the big picture, this is a thumbnail (albeit a large one!) illustrating the complete solution for documenting PowerShell APIs. Note that besides DocTreeGenerator, this also includes the other crucial 3rd party tool you need, XmlDoc2CmdletDoc.

Documenting PowerShell Cmdlets End-toEnd

Download the full wallchart in a convenient PDF from my article on Simple-Talk.com: Unified Approach to Generating Documentation for PowerShell Cmdlets.

Installation

  1. If you have Windows 10 or later (or have updated your PS 3 or 4 environment with PowerShellGet), you can just run Install-Module -Name DocTreeGenerator to install this module from the PowerShell Gallery. Otherwise, you can download it from GitHub. After downloading, unzip DocTreeGenerator-master.zip into your PowerShell Modules directory ($env:UserProfile\Documents\WindowsPowerShell\Modules) and drop the "-master" suffix on the extracted folder.
  2. Import the module in your profile or import it manually: Import-Module DocTreeGenerator

Usage

See extensive help available from Get-Help Convert-HelpToHtmlTree and Get-Help Publish-ModuleDocumentationTree. Also see some practical examples and detailed notes on how to use it on Simple-Talk.com: How To Document Your PowerShell Library

You can see a real-world example of its use on my open source website, showing a tree complete with an index to all functions and modules: CleanCode PowerShell Libraries And adjacent to this "readme" file is a rendering of the help for Convert-HelpToHtmlTree itself (Convert-HelpToHtmlTree.html).

Notes

DocTreeGenerator uses the output of Get-Help as its input; some of the vagaries of Get-Help can be compensated for, but not always. Known issues are itemized below. The designation [PS] applies to cmdlets written in PowerShell, while [C#] applies to cmdlets written in C#.

Other issues in this section are things to watch out for that might cause undo consternation.

Preformatted Blocks in Examples

[PS] You cannot have a preformatted block immediately following an example (a tab or 4+ leading spaces signals a preformatted line). If you do, the first line--in this example the column headers--will not be preformatted. (You can observe this problem if you just run Get-Help for your cmdlet on the command-line.)

============ EXCERPT FROM A PS DOC-COMMENT SECTION ============================
.EXAMPLE
PS> Show-Packages .\default.proj
	Name              DependsOnTargets        CallTarget
	----              ----------------        ----------
	All                                       Clean;RestorePackages;Build
	Test              UnitTest;IntegrationTest
	Analyze
===============================================================================

Remedy: Add a regular text paragraph between the line of code and the start of the preformatted block:

============ EXCERPT FROM A PS DOC-COMMENT SECTION ============================
.EXAMPLE
PS> Show-Packages .\default.proj
This line could say anything; mainly it is to fix Get-Help's formatting issue!
	Name              DependsOnTargets        CallTarget
	----              ----------------        ----------
	All                                       Clean;RestorePackages;Build
	Test              UnitTest;IntegrationTest
	Analyze
===============================================================================
Watch out for inadvertent list indicators

[PS,C#] If you start a line with an asterisk, plus, or minus, you are asking to force a line break. (Presumably you are enumerating items in a list.) But watch out that you do not do this inadvertantly. (If, for example, you are talking about code you might mention a "-Force" option--just make sure that is not the first thing on the line, otherwise it will end the paragraph prematurely at that point.)

Leading spaces are your friend if used wisely

[PS,C#] If you start a line with a space, this also forces a line break. This is very useful, for example, if you want example code to span multiple lines in the HTML rendered output. Use a couple leading spaces on each line after the first that you want to start on a new line. (But do NOT use more than 3--otherwise you trigger generating a pre-formatted block, which is likely not what you want.)

Multi-line code samples in examples

[PS,C#] Also useful for code examples: start a line with "PS>", i.e. a canonical PowerShell prompt, and this also forces a line break. Thus, if you want to show multiple separate commands, start each line with "PS>". (Contrast that with if you want to show multiple piped commands, just use a leading space or two on each line per the previous point above.

doctreegenerator's People

Contributors

ebekker avatar msorens avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

doctreegenerator's Issues

Add support for modules located in arbitrary directory

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.

Publish DTG on PowerShell Gallery

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

Hyperlinks not being generated for custom functions from other local modules

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.

Indentation issues in Example section

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

image

/cc @prithvibv

Anomalies in Example section

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.

Wildcard in Namespace selector should be resolved before using for page title

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.

exact makeup of the overview.html files remains unclear

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.

Problem when two modules contain a function with the same name

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.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.