DefaultDocumentation 1.0.0-beta04
dotnet add package DefaultDocumentation --version 1.0.0-beta04
NuGet\Install-Package DefaultDocumentation -Version 1.0.0-beta04
<PackageReference Include="DefaultDocumentation" Version="1.0.0-beta04"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
paket add DefaultDocumentation --version 1.0.0-beta04
#r "nuget: DefaultDocumentation, 1.0.0-beta04"
// Install DefaultDocumentation as a Cake Addin #addin nuget:?package=DefaultDocumentation&version=1.0.0-beta04&prerelease // Install DefaultDocumentation as a Cake Tool #tool nuget:?package=DefaultDocumentation&version=1.0.0-beta04&prerelease
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.
<a name='Requirement'></a>
Requirement
- for the msbuild task: any runtime supporting netstandard2.0
- for the dotnet tool: netcore3.1, net5.0 or net6.0
<a name='Usage'></a>
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.
<a name='Usage_MSBuildTask'></a>
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>
<a name='Usage_DotnetTool'></a>
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
<a name='Overview'></a>
Overview
List of supported balises and attributes taken from here with some additions.
List of supported members taken from here
<a name='Overview_Exclude'></a>
Exclude documentation
It is possible to exclude a type/member from the generated documentation by adding a <exclude/>
element to its xml documentation.
<a name='Overview_Inherit'></a>
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.
<a name='Overview_Assembly'></a>
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
}
<a name='Overview_Namespace'></a>
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
}
<a name='Overview_Links'></a>
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.
<a name='Overview_Plugins'></a>
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.
<a name='Configuration'></a>
Configuration
Here is all the available settings to help you build your documentation as you wish.
<a name='Configuration_ConfigurationFilePath'></a>
ConfigurationFilePath
- csproj property:
<DefaultDocumentationConfigurationFile>...</DefaultDocumentationConfigurationFile>
, default value isDefaultDocumentation.json
in the project folder - tool argument:
-j ...
--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.
<a name='Configuration_LogLevel'></a>
LogLevel
- csproj property:
<DefaultDocumentationLogLevel>...</DefaultDocumentationLogLevel>
- tool argument:
-h ...
--LogLevel ...
- configuration file:
"LogLevel": "..."
The minimum level of the log you wish to be displayed to help resolve errors, Info
by default. Available values are:
Trace
: Trace log levelDebug
: Debug log levelInfo
: Info log levelWarn
: Warn log levelError
: Error log levelFatal
: Fatal log levelOff
: no log
<a name='Configuration_AssemblyFilePath'></a>
AssemblyFilePath
- csproj property: this setting is set automatically for you by the msbuild task
- tool argument:
-a ...
--AssemblyFilePath ...
- configuration file:
"AssemblyFilePath": "..."
The path to the assembly file you wish to create documentation for.
<a name='Configuration_DocumentationFilePath'></a>
DocumentationFilePath
- csproj property: this setting is set automatically for you by the msbuild task
- tool argument:
-d ...
--DocumentationFilePath ...
- configuration file:
"DocumentationFilePath": "..."
The path to the xml documentation file, if not specified DefaultDocumentation will assume it is in the same folder as the assembly.
<a name='Configuration_ProjectDirectoryPath'></a>
ProjectDirectoryPath
- csproj property: this setting is set automatically for you by the msbuild task
- tool argument:
-p ...
--ProjectDirectoryPath ...
- configuration file:
"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.
<a name='Configuration_OutputDirectoryPath'></a>
OutputDirectoryPath
- csproj property:
<DefaultDocumentationFolder>...</DefaultDocumentationFolder>
- tool argument:
-o ...
--OutputDirectoryPath ...
- configuration file:
"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.
<a name='Configuration_AssemblyPageName'></a>
AssemblyPageName
- csproj property:
<DefaultDocumentationAssemblyPageName>...</DefaultDocumentationAssemblyPageName>
- tool argument:
-n ...
--AssemblyPageName ...
- configuration 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.
<a name='Configuration_GeneratedAccessModifiers'></a>
GeneratedAccessModifiers
- csproj property:
<DefaultDocumentationGeneratedAccessModifiers>...,...</DefaultDocumentationGeneratedAccessModifiers>
- tool argument:
-s ...,...
--GeneratedAccessModifiers ...,...
- configuration file:
"GeneratedAccessModifiers": "...,..."
State elements with which access modifier should be generated. All by default, available values are:
Public
: generates documentation for 'public' access modifierPrivate
: generates documentation for 'private' access modifierProtected
: generates documentation for 'protected' access modifierInternal
: generates documentation for 'internal' access modifierProtectedInternal
: generates documentation for 'protected internal' access modifierPrivateProtected
: generates documentation for 'private protected' access modifierApi
: generates documentation for 'public', 'protected' and 'protected internal' access modifier.
<a name='Configuration_IncludeUndocumentedItems'></a>
IncludeUndocumentedItems
- csproj property:
<DefaultDocumentationIncludeUndocumentedItems>...</DefaultDocumentationIncludeUndocumentedItems>
- tool argument:
-u
--IncludeUndocumentedItems
- configuration file:
"IncludeUndocumentedItems": "..."
If true
items with no documentation will also be included in the generated documentation. false
by default.
<a name='Configuration_GeneratedPages'></a>
GeneratedPages
- csproj property:
<DefaultDocumentationGeneratedPages>...,...</DefaultDocumentationGeneratedPages>
- tool argument:
-g ...,...
--GeneratedPages ...,...
- configuration file:
"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:
Assembly
: the assembly should have its own page, see AssemblyPageName for case when the assembly will have its page generated regardless of this flag being presentNamespaces
: namespaces should have their own pagesClasses
: classes should have their own pagesDelegates
: delegates should have their own pagesEnums
: enums should have their own pagesStructs
: structs should have their own pagesInterfaces
: interfaces should have their own pagesTypes
: equivalent toClasses, Delegates, Enums, Structs, Interfaces
Constructors
: constructors should have their own pagesEvents
: events should have their own pagesFields
: fields should have their own pagesMethods
: methods should have their own pagesOperators
: operators should have their own pagesProperties
: properties should have their own pagesExplicitInterfaceImplementations
: property and method explicit interface implementations should have their own pagesMembers
: equivalent toConstructors, Events, Fields, Methods, Operators, Properties, ExplicitInterfaceImplementations
<a name='Configuration_LinksOutputFilePath'></a>
LinksOutputFilePath
- csproj property:
< sOutputFile>...</DefaultDocumentationLinksOutputFile>
- tool argument:
-l ...
--LinksOutputFilePath ...
- configuration file:
"LinksOutputFilePath": "..."
Where to generate the links file, see Extern links for more information, empty by default and does not generate the links file.
<a name='Configuration_LinksBaseUrl'></a>
LinksBaseUrl
- csproj property:
<DefaultDocumentationLinksBaseUrl>...</DefaultDocumentationLinksBaseUrl>
- tool argument:
-b ...
--LinksBaseUrl ...
- configuration file:
"LinksBaseUrl": "..."
The base url to use for the links file, see Extern links for more information.
<a name='Configuration_ExternLinksFilePaths'></a>
ExternLinksFilePaths
- csproj property:
<DefaultDocumentationExternLinksFiles>...|...</DefaultDocumentationExternLinksFiles>
- tool argument:
-e ...|...
--ExternLinksFilePaths ...|...
- configuration file:
"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
.
<a name='Configuration_Plugins'></a>
Plugins
- csproj property:
<DefaultDocumentationPlugins>...|...</DefaultDocumentationPlugins>
- tool argument:
--Plugins ...|...
- configuration file:
"Plugins": [ "...", "..." ]
The list of plugin files to load to create the documentation. See Plugins for more information.
<a name='Configuration_DocItemGenerators'></a>
DocItemGenerators
- csproj property:
<DefaultDocumentationDocItemGenerators>...|...</DefaultDocumentationDocItemGenerators>
- tool argument:
--DocItemGenerators ...|...
- configuration file:
"DocItemGenerators": [ "...", "..." ]
Name
or Type Assembly
of the IDocItemGenerator
implementations to use to generate the DocItem
of the documentation.
The default implementations provided are:
Exclude
orDefaultDocumentation.Markdown.DocItemGenerators.ExcludeGenerator DefaultDocumentation.Markdown
removeDocItem
from the documentation generation based on MarkdownConfiguration.Exclude.Overloads
orDefaultDocumentation.Markdown.DocItemGenerators.OverloadsGenerator DefaultDocumentation.Markdown
adds pages to group constructor and method overloads the same way microsoft documentation do it. The default value isExclude|Overloads
.
<a name='Configuration_UrlFactories'></a>
UrlFactories
- csproj property:
<DefaultDocumentationUrlFactories>...|...</DefaultDocumentationUrlFactories>
- tool argument:
--UrlFactories ...|...
- configuration file:
"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:
DocItem
orDefaultDocumentation.Markdown.UrlFactories.DocItemFactory DefaultDocumentation.Markdown
returns an url for knownDocItem
.DotnetApi
orDefaultDocumentation.Markdown.UrlFactories.DotnetApiFactory DefaultDocumentation.Markdown
returns an url formated from the id to its possible dotnet api documentation. The default value isDocItem|DotnetApi
.
<a name='Configuration_Elements'></a>
Elements
- csproj property:
<DefaultDocumentationElements>...|...</DefaultDocumentationElements>
- tool argument:
--Elements ...|...
- configuration file:
"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:
DefaultDocumentation.Markdown.Elements.CElement DefaultDocumentation.Markdown
handle the rendering of<c>
elementDefaultDocumentation.Markdown.Elements.CodeElement DefaultDocumentation.Markdown
handle the rendering of<code>
element. Attributes handled are:language
attribute used to declare the languge of the codesource
attribute used to reference code from a specific fileregion
attribute used to reference a specific#region
from the source
DefaultDocumentation.Markdown.Elements.ListElement DefaultDocumentation.Markdown
handle the rendering of<list>
elementDefaultDocumentation.Markdown.Elements.NoteElement DefaultDocumentation.Markdown
handle the rendering of<note>
elementDefaultDocumentation.Markdown.Elements.ParaElement DefaultDocumentation.Markdown
handle the rendering of<para>
element. Attributes handled are:ignorelinebreak
attribute used to change the default setting of IgnoreLineBreak for the content of this element
DefaultDocumentation.Markdown.Elements.ParamRefElement DefaultDocumentation.Markdown
handle the rendering of<paramref>
elementDefaultDocumentation.Markdown.Elements.SeeElement DefaultDocumentation.Markdown
handle the rendering of<see>
. Attributes handled are:cref
attributehref
attributelangword
attribute
DefaultDocumentation.Markdown.Elements.TypeParamRefElement DefaultDocumentation.Markdown
handle the rendering of<typeparamref>
element
<a name='DocItemConfiguration'></a>
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:
AssemblyDocItem
NamespaceDocItem
ClassDocItem
StructDocItem
InterfaceDocItem
EnumDocItem
DelegateDocItem
ConstructorDocItem
EnumFieldDocItem
EventDocItem
ExplicitInterfaceImplementationDocItem
FieldDocItem
MethodDocItem
OperatorDocItem
PropertyDocItem
TypeParameterDocItem
ParameterDocItem
<a name='DocItemConfiguration_FileNameFactory'></a>
FileNameFactory
- csproj property:
<DefaultDocumentationFileNameFactory>...</DefaultDocumentationFileNameFactory>
- tool argument:
--FileNameFactory ...
- configuration file:
"FileNameFactory": "..."
Name
or Type Assembly
of the IFileNameFactory
implementation to use to generate the name of pages. Available implementations are:
FullName
orDefaultDocumentation.Markdown.FileNameFactories.FullNameFactory DefaultDocumentation.Markdown
uses the fully qualified name of each memberName
orDefaultDocumentation.Markdown.FileNameFactories.NameFactory DefaultDocumentation.Markdown
removes the namespace (collisions can happen if there is multiple types with the same name in different namespaces)Md5
orDefaultDocumentation.Markdown.FileNameFactories.Md5Factory DefaultDocumentation.Markdown
uses a Md5 of the full name of each member to produce shorter name, collisions can happenNameAndMd5Mix
orDefaultDocumentation.Markdown.FileNameFactories.NameAndMd5MixFactory DefaultDocumentation.Markdown
removes the namespace and use a Md5 for parametersDirectoryName
orDefaultDocumentation.Markdown.FileNameFactories.DirectoryNameFactory DefaultDocumentation.Markdown
use a directory hierarchy The default value isFullName
. All those implementations WILL delete any.md
file EXCEPT a file namedreadme.md
.
<a name='DocItemConfiguration_Sections'></a>
Sections
- csproj property:
<DefaultDocumentationSections>...|...</DefaultDocumentationSections>
- tool argument:
--Sections ...|...
- configuration file:
"Sections": [ "...", "..." ]
Name
or Type Assembly
of the ISection
implementations to use in order for the generation of the documentation. The available implentations are:
Header
orDefaultDocumentation.Markdown.Sections.HeaderSection DefaultDocumentation.Markdown
to write links to parents and top pagesFooter
orDefaultDocumentation.Markdown.Sections.FooterSection DefaultDocumentation.Markdown
to write a reference to this projectTypeParameters
orDefaultDocumentation.Markdown.Sections.TypeParametersSection DefaultDocumentation.Markdown
to write theTypeParameterDocItem
children links or inlined documentationParameters
orDefaultDocumentation.Markdown.Sections.ParametersSection DefaultDocumentation.Markdown
to write theParameterDocItem
children links or inlined documentationEnumFields
orDefaultDocumentation.Markdown.Sections.EnumFieldsSection DefaultDocumentation.Markdown
to write theEnumFieldDocItem
children links or inlined documentationConstructors
orDefaultDocumentation.Markdown.Sections.ConstructorsSection DefaultDocumentation.Markdown
to write theConstructorDocItem
children links or inlined documentationFields
orDefaultDocumentation.Markdown.Sections.FieldsSection DefaultDocumentation.Markdown
to write theFieldDocItem
children links or inlined documentationProperties
orDefaultDocumentation.Markdown.Sections.PropertiesSection DefaultDocumentation.Markdown
to write thePropertyDocItem
children links or inlined documentationMethods
orDefaultDocumentation.Markdown.Sections.MethodsSection DefaultDocumentation.Markdown
to write theMethodDocItem
children links or inlined documentationEvents
orDefaultDocumentation.Markdown.Sections.EventsSection DefaultDocumentation.Markdown
to write theEventDocItem
children links or inlined documentationOperators
orDefaultDocumentation.Markdown.Sections.OperatorsSection DefaultDocumentation.Markdown
to write theOperatorDocItem
children links or inlined documentationExplicitInterfaceImplementations
orDefaultDocumentation.Markdown.Sections.ExplicitInterfaceImplementationsSection DefaultDocumentation.Markdown
to write theExplicitInterfaceImplementationDocItem
children links or inlined documentationClasses
orDefaultDocumentation.Markdown.Sections.ClassesSection DefaultDocumentation.Markdown
to write theClassDocItem
children links or inlined documentationStructs
orDefaultDocumentation.Markdown.Sections.StructsSection DefaultDocumentation.Markdown
to write theStructDocItem
children links or inlined documentationInterfaces
orDefaultDocumentation.Markdown.Sections.InterfacesSection DefaultDocumentation.Markdown
to write theInterfaceDocItem
children links or inlined documentationEnums
orDefaultDocumentation.Markdown.Sections.EnumsSection DefaultDocumentation.Markdown
to write theEnumDocItem
children links or inlined documentationDelegates
orDefaultDocumentation.Markdown.Sections.DelegatesSection DefaultDocumentation.Markdown
to write theDelegateDocItem
children links or inlined documentationNamespaces
orDefaultDocumentation.Markdown.Sections.NamespacesSection DefaultDocumentation.Markdown
to write theNamespaceDocItem
children links or inlined documentationDefinition
orDefaultDocumentation.Markdown.Sections.DefinitionSection DefaultDocumentation.Markdown
to write the code definitionDerived
orDefaultDocumentation.Markdown.Sections.DerivedSection DefaultDocumentation.Markdown
to write links to derived typesEventType
orDefaultDocumentation.Markdown.Sections.EventTypeSection DefaultDocumentation.Markdown
to write the event type forEventDocItem
FieldValue
orDefaultDocumentation.Markdown.Sections.FieldValueSection DefaultDocumentation.Markdown
to write the field value forFieldDocItem
Implement
orDefaultDocumentation.Markdown.Sections.ImplementSection DefaultDocumentation.Markdown
to write links to implementationsInheritance
orDefaultDocumentation.Markdown.Sections.InheritanceSection DefaultDocumentation.Markdown
to write links to the inherited typesTableOfContents
orDefaultDocumentation.Markdown.Sections.TableOfContentsSection DefaultDocumentation.Markdown
to write a table of content links to all children, see TableOfContentsModes settingTitle
orDefaultDocumentation.Markdown.Sections.TitleSection DefaultDocumentation.Markdown
to write the title and link target of aDocItem
Definition
orDefaultDocumentation.Markdown.Sections.DefinitionSection DefaultDocumentation.Markdown
to write the code definitionDefault
orDefaultDocumentation.Markdown.Sections.DefaultSection DefaultDocumentation.Markdown
is a grouping of thoseISection
implementations in this order:DefaultDocumentation.Markdown.Sections.TitleSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.SummarySection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.DefinitionSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.TypeParametersSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.ParametersSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.EnumFieldsSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.InheritanceSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.DerivedSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.ImplementSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.EventTypeSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.FieldValueSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.ValueSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.ReturnsSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.ExceptionSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.ExampleSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.RemarksSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.SeeAlsoSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.NamespacesSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.ClassesSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.StructsSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.InterfacesSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.EnumsSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.DelegatesSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.ConstructorsSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.FieldsSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.PropertiesSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.MethodsSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.EventsSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.OperatorsSection DefaultDocumentation.Markdown
DefaultDocumentation.Markdown.Sections.ExplicitInterfaceImplementationsSection DefaultDocumentation.Markdown
example
orDefaultDocumentation.Markdown.Sections.ExampleSection DefaultDocumentation.Markdown
to write the<example>
elementignorelinebreak
attribute used to change the default setting of IgnoreLineBreak for the content of this element
exception
orDefaultDocumentation.Markdown.Sections.ExceptionSection DefaultDocumentation.Markdown
to write the<exception>
elementscref
attributeignorelinebreak
attribute used to change the default setting of IgnoreLineBreak for the content of this element
remarks
orDefaultDocumentation.Markdown.Sections.RemarksSection DefaultDocumentation.Markdown
to write the<remarks>
elementignorelinebreak
attribute used to change the default setting of IgnoreLineBreak for the content of this element
returns
orDefaultDocumentation.Markdown.Sections.ReturnsSection DefaultDocumentation.Markdown
to write the<returns>
elementignorelinebreak
attribute used to change the default setting of IgnoreLineBreak for the content of this element
seealso
orDefaultDocumentation.Markdown.Sections.SeeAlsoSection DefaultDocumentation.Markdown
to write the<seealso>
elementscref
attributehref
attribute
summary
orDefaultDocumentation.Markdown.Sections.SummarySection DefaultDocumentation.Markdown
to write the<summary>
elementignorelinebreak
attribute used to change the default setting of IgnoreLineBreak for the content of this element
value
orDefaultDocumentation.Markdown.Sections.ValueSection DefaultDocumentation.Markdown
to write the<value>
elementignorelinebreak
attribute used to change the default setting of IgnoreLineBreak for the content of this element
The default value is Header|Default
.
<a name='MarkdownConfiguration'></a>
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.
<a name='MarkdownConfiguration_NestedTypeVisibilities'></a>
NestedTypeVisibilities
- configuration file:
"Markdown.NestedTypeVisibilities": "...,..."
States where nested types should be visible. Available values are:
Namespace
: nested types will be displayed in their parent namespaceDeclaringType
: nested types will be displayed in their parent type
Default value is Namespace
.
This setting can be overriden by specific DocItem
types.
<a name='MarkdownConfiguration_RemoveFileExtensionFromUrl'></a>
RemoveFileExtensionFromUrl
- configuration file:
"Markdown.RemoveFileExtensionFromUrl": "..."
true
to remove the extension .md
from links in the generated documentation, some wikies don't like those. false
by default.
<a name='MarkdownConfiguration_InvalidCharReplacement'></a>
InvalidCharReplacement
- configuration file:
"Markdown.InvalidCharReplacement": "..."
Provides the value to use to replace invalid char for file names, _
by default.
<a name='MarkdownConfiguration_HandleLineBreak'></a>
HandleLineBreak
- configuration file:
"Markdown.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.
<a name='MarkdownConfiguration_TableOfContentsModes'></a>
TableOfContentsModes
- configuration file:
"Markdown.TableOfContentsModes": "...,..."
States how the table of contents should be rendered. Available values are:
Grouped
: eachDocItem
kind should be grouped in their own sectionIncludeKind
: display the kind of eachDocItem
explicitelyIncludeSummary
: the<summary>
element of theDocItem
should be displayedIncludeNewLine
: their should be a newline between theDocItem
name and its<summary>
if displayedIncludeSummaryWithNewLine
: same asIncludeSummary,IncludeNewLine
This setting can be overriden by specific DocItem
types.
<a name='MarkdownConfiguration_UrlFormat'></a>
Url format
- configuration file:
"Markdown.UrlFormat": ""
State the format that will be used to display urls.
Three arguments will be passed to the format:
- the displayed text
- the url
- the tooltip to display when overing the link. If null the url will be used
The default value is [{0}]({1} '{2}')
.
<a name='MarkdownConfiguration_Exclude'></a>
Exclude
- configuration file:
"Markdown.Exclude": [ "", ... ]
Contains a collection of regex used by the DefaultDocumentation.Markdown.DocItemGenerators.ExcludeGenerator DefaultDocumentation.Markdown
DocItemGenerator,
any DocItem
whose id will match one of them will be excluded from the documentation generation.
The default value is null
.
<a name='MarkdownConfiguration_UseFullUrl'></a>
UseFullUrl
- configuration file:
"Markdown.UseFullUrl": bool
States if the url written should be absolute if a LinksBaseUrl is provided.
The default value is false
.
<a name='Samples'></a>
Samples
<a name='Dependencies'></a>
Dependencies
DefaultDocumentation is only made possible thanks to those awesome projects:
CI, tests and code quality rely on those awesome projects:
Learn more about Target Frameworks and .NET Standard.
This package has no dependencies.
NuGet packages (13)
Showing the top 5 NuGet packages that depend on DefaultDocumentation:
Package | Downloads |
---|---|
Ustilz.Time
Utility for work with dates and durations |
|
Ustilz.Utils
Package Description |
|
Ustilz.Extensions
Package Description |
|
Ustilz.Json
Package Description |
|
Ustilz.Xml
Package Description |
GitHub repositories (5)
Showing the top 5 popular GitHub repositories that depend on DefaultDocumentation:
Repository | Stars |
---|---|
nxrighthere/UnrealCLR
Unreal Engine .NET 6 integration
|
|
Doraku/DefaultEcs
Entity Component System framework aiming for syntax and usage simplicity with maximum performance for game development.
|
|
gurrenm3/BTD-Mod-Helper
A powerful and easy to use API for modding BTD6, BATTD, and other Ninja Kiwi games.
|
|
lazlo-bonin/gocs
GameObject Component System for Unity
|
|
dymaptic/GeoBlazor
Core Components for the Dymaptic GeoBlazor Library
|
Version | Downloads | Last updated |
---|---|---|
1.0.0-beta04 | 148 | 11/6/2024 |
1.0.0-beta03 | 238 | 11/1/2024 |
1.0.0-beta02 | 84 | 10/23/2024 |
1.0.0-beta01 | 74 | 10/23/2024 |
0.9.0-beta02 | 136 | 10/18/2024 |
0.9.0-beta01 | 93 | 10/14/2024 |
0.8.3-beta1 | 14,202 | 6/26/2022 |
0.8.2 | 88,283 | 6/12/2022 |
0.8.1 | 2,681 | 5/1/2022 |
0.8.0 | 4,082 | 3/19/2022 |
0.7.9 | 26,086 | 9/26/2021 |
0.7.7 | 2,008 | 9/11/2021 |
0.7.6 | 1,811 | 9/3/2021 |
0.7.5 | 6,410 | 6/16/2021 |
## Breaking changes
- renamed Markdown.IgnoreLineBreak setting to Markdown.HandleLineBreak to change default behavior (#122)
## New features
- added DefaultDocumentation.GeneratedAccessModifiers.Api which regroup Public, Protected and InternalProtected access modifiers (#116)
- added support for record
- elements, url factories, file name factory and sections are now case insensitive in configuration (#157)
- it is now possible to change the format of url link procuded in the markdown via Markdown.UrlFormat configuration (#107)
- added IDocItemGenerator to customize pages generated
- added OverloadsGenerator to put constructor and method overloads in the same page (#139)
- added ExcludeGenerator to exclude DocItem from the documentation generation based on regex (#160)
- list code and note elements now display a placeholder value `...` when displayed as a single line
- added DirectoryName IFileNameFactory implementation (#104)
- added some settings validation for better error message (#154)
## Bug fixes
- fixed string and char const field definition
- fixed ExplicitInterfaceImplementationsSection config name (#141)
- fixed StackOverflowException when using cyclic inheritdoc (#142)
- fixed property getter/setter access modifier not taken into account (#151)
- fixed markdown special characters not escaped (#117)
- fixed unhandled xml elements not rendering as is in markdown (#126)
- fixed issue with list rendering
- fixed enum fields to respect code order (#131)
- fixed c and see elements with leading and trailing linebreak chars (#113)
- fixed plugins loading in certain context (#145 thanks to @a10r)
- fixed edge case for missing types for explicit interface implementation (#167)