search

Doraku / DefaultDocumentation

Create a simple markdown documentation from the Visual Studio xml one.
MIT No Attribution
157 stars 26 forks source link
c-sharp documentation markdown

readme

DefaultDocumentation

As the name imply, this project lets you easily produce a markdown documentation from the generated assembly and its xml documentation produced by visual studio from comments.

Coverage Status continuous integration status
api NuGet api preview api
msbuild task NuGet msbuild task preview msbuild task
dotnet tool NuGet dotnet tool preview dotnet tool

Requirement

Usage

DefaultDocumentation is available in two flavour, an msbuild task automatically integrated in a post build target when referencing the nuget package, using msbuild properties to configure it and a dotnet tool console.

MSBuild task

Simply reference the DefaultDocumentation package in the projet you want to generate documentation for (don't worry it's only a development dependencies, no dlls will be added to your project). If the property <DocumentationFile> or <GenerateDocumentationFile> are set, the markdown pages will be produced automatically after a successfull build, that's it!
You can disable the documentation generation by setting the <DisableDefaultDocumentation> to true in your csproj.

...
<Project Sdk="Microsoft.NET.Sdk">
    ...
    <PropertyGroup>
        <GenerateDocumentationFile>true</GenerateDocumentationFile>
    </PropertyGroup>
    ...
    <ItemGroup>
        <PackageReference Include="DefaultDocumentation" Version="0.8.0" PrivateAssets="all"/>
    </ItemGroup>
    ...
</Project>

Dotnet tool

DefaultDocumentation is also available as a dotnet tool if you need to control when to produce the documentation. The tool command is simply defaultdocumentation. To install the tool simply use this command:

dotnet tool install DefaultDocumentation.Console -g

Overview

List of supported balises and attributes taken from here with some additions.

List of supported members taken from here

Exclude documentation

It is possible to exclude a type/member from the generated documentation by adding a <exclude/> element to its xml documentation.

Inherit documentation

The <inheritdoc> element is supported to reused existing documentations if available. Note that this is a full import of the inherited documentation, any additional xml documentation will be ignored.

Assembly documentation

It is possible to declare xml documentation for your assembly by adding a special class named AssemblyDoc in a namespace with the name of the assembly.

namespace YourAssemblyName
{
    /// <summary>
    /// your assembly documentation, used on the assembly page
    /// </summary>
    internal static class AssemblyDoc { } // internal so it is not visible outside the assembly
}

Namespace documentation

It is possible to declare xml documentation for a namespace by adding a special class named NamespaceDoc in the desired namespace.

namespace YourNamespace
{
    /// <summary>
    /// your namespace documentation
    /// </summary>
    internal static class NamespaceDoc { } // internal so it is not visible outside the assembly
}

Extern links

When using cref attributes, you may refer items from other assemblies which DefaultDocumentation has no knowledge of their documentation location. By default, it will use the provided UrlFactories that may produce incorrect links.
To remedy this, DefaultDocumentation use files for explicit links with the following simple format:

http://extern/assembly/documentation/base/url/
T:ExternAssembly.ExternType|extern_type.html|ExternType
M:ExternAssembly.ExternType.ExternMethod|extern_type_extern_method.html|ExternType

The first element is the base url that will be put before each following documentation page.
After that, you can have as many items with the following format: entity id|base url relative link to the documentation page|display name to use (optional).
You can change the base url in the same file for the following items.

http://extern/assembly/documentation/base/url/
T:ExternAssembly.ExternType|extern_type.html|ExternType
M:ExternAssembly.ExternType.ExternMethod|extern_type_extern_method.html|ExternType
http://extern/other/assembly/documentation/base/url/
T:OtherExternAssembly.ExternType|extern_type.html|ExternType

DefaultDocumentation can generate this file automatically for your assembly as it generates its documentation so can you easilly reference your own assembly documentation in other project, see LinksOutputFilePath and LinksBaseUrl settings.

Links files have no defined extension.

Plugins

DefaultDocumentation is completely extensible in the form of plugin. The api serves as a base for contracts you can use to add features to your own documentation generation.
See the api reference for the list of interfaces for which you can provide your own implementations.
See Plugins setting for how to use a plugin and the samples for examples of implementations.

Configuration

Here is all the available settings to help you build your documentation as you wish.

ConfigurationFilePath

The path to a json configuration file. If values are also provided by csproj property (msbuild task usage) or argument (tool usage) they will override what is inside the configuration file.
Note that using a configuration file allow you to provide specific settings per DocItem type. See DocItem Configuration for more informations.
All relative path specified in the configuration file are relative to the actual configuration file path.

LogLevel

The minimum level of the log you wish to be displayed to help resolve errors, Info by default. Available values are:

AssemblyFilePath

The path to the assembly file you wish to create documentation for.

DocumentationFilePath

The path to the xml documentation file, if not specified DefaultDocumentation will assume it is in the same folder as the assembly.

ProjectDirectoryPath

the path to the project source folder. This is only used if you reference a file using a source attribute in a <code> element.

OutputDirectoryPath

The path to the output folder where the documentation will be generated. If not specified, the pages will be generated in the same folder as the xml documentation file.

AssemblyPageName

The name of the page for the assembly documentation.
Note that this page will not be generated if you do not provide a name for this setting and there is only one namespace in your project and there is no xml documentation for the assembly (see Assembly documentation).
If you did not provide a name but the page still need to be generated, the default name index will be used.

GeneratedAccessModifiers

State elements with which access modifier should be generated. All by default, available values are:

IncludeUndocumentedItems

If true items with no documentation will also be included in the generated documentation. false by default.

GeneratedPages

States which item should have their own pages, if not their documentation will be inlined in their parent's one, Namespaces,Types,Members by default. Available values are:

LinksOutputFilePath

Where to generate the links file, see Extern links for more information, empty by default and does not generate the links file.

LinksBaseUrl

The base url to use for the links file, see Extern links for more information.

ExternLinksFilePaths

The list of links files to use when generating the documentation, see Extern links for more information.
You can use pattern, ex: .\myfolder\*.txt.

Plugins

The list of plugin files to load to create the documentation. See Plugins for more information.

UrlFactories

Name or Type Assembly of the IUrlFactory implementations to use to create documentation url. The element id is passed to each successive implementations and the first non null returned url is used. The default implementations provided are:

Elements

Type Assembly of the explicit IElement implementations to use to create the documentation.
By default all implementations are used but if multiple ones have the same name, the one from the latest plugin loaded is used. In case you may want to use a plugin that contains an IElement implementation but still use one from an other plugin, you can force its usage by stating its Type Assembly explicitely. The default implementations provided are:

DocItem Configuration

Those next settings can be overrided for each DocItem type when using a configuration file, allowing you to have different settings for each type. If no specific setting is defined for a given type, the root setting will be used.

{
    "Sections": [
        "Header",
        "Default",
    ]
    "NamespaceDocItem": {
        "Sections": [
            "Title",
            "summary",
            "TableOfContents"
        ]
    }
}

The different DocItem types are:

FileNameFactory

Name or Type Assembly of the IFileNameFactory implementation to use to generate the name of pages. Available implementations are:

Sections

Name or Type Assembly of the ISection implementations to use in order for the generation of the documentation. The available implentations are:

The default value is Header|Default.

Markdown Configuration

The default implementations to generate markdown documentation also comes with its own specific settings. Those can only be set in the configuration file and may or may not be overridable by specific DocItem types.

NestedTypeVisibilities

States where nested types should be visible. Available values are:

Default value is Namespace.
This setting can be overriden by specific DocItem types.

RemoveFileExtensionFromUrl

true to remove the extension .md from links in the generated documentation, some wikies don't like those. false by default.

InvalidCharReplacement

Provides the value to use to replace invalid char for file names, _ by default.

HandleLineBreak

true if line break in the documentation should be transformed as markdown line break (two space at the end of a line) or not, false by default.
This setting can be overriden by specific DocItem types.

TableOfContentsModes

States how the table of contents should be rendered. Available values are:

This setting can be overriden by specific DocItem types.

Samples

Dependencies

DefaultDocumentation is only made possible thanks to those awesome projects:

CI, tests and code quality rely on those awesome projects: