Problem
Imagine you have a .NET Core class library fully commented with XMLDoc and you want to publish the documentation for your library on the web. Here is where Aistant service (with a special Aistdoc console utility) comes to help.
1. Registration in Aistant
The first, obvious step, is a registering a new account on Aistant (if you don't have it yet). Choose "Empty" option when it asks about your new Knowledge Base's default content.
After the registration please open Users page in Aistant Console and set the password for the special service account (YourTeamID-clientapp@aistant.com) which was created automatically for your team. Save the password somewhere. It will be used to setup the credentials to your Aistant account in the configuration file for AistDoc (see below).
2. Installing AistDoc
Aistdoc utility scans your library assemblies and XML documentation files, generates articles (one article for each class, interface or enum) and uploads them to your knowledge base on Aistant.
NB: Before installing Aistdoc you will need .NET Core SDK (version 2.1 or higher) be installed on your computer. Since we are talking about the publishing of documentation for a .NET library here - we guess you already have one.
Aistdoc is implemented as a .NET Core Global Tool, so its installation is quite simple:
dotnet tool install -g Aistant.DocImport
To update it to the latest version, if it was installed previously, use:
dotnet tool update -g Aistant.DocImport
3. How to use
Preparing your library files
- Make sure you turned on "XML documentation file" option in all projects for which you plan to publish the documentation.
- Build all projects in your library.
- Place all assemblies (DLL files) and XML documentation files to one folder.
Configuration file
Aistdoc reads all settings from a special JSON configuration file. To generate a template for that file use the following command:
aistdoc create -f:<config file name> -m:cs
Here -f (or --file) parameter allows to specify the name of the config file and -m (or --mode) specifies the mode (either ts for TypeScript or cs for C#).
For example, the following command
aistdoc create -f:mylib.json -m:cs
will create mylib.json config file in the current folder.
The config file has 2 main sections: aistant and source.
The first one contains the credentials to your Aistant account, the ID of the knowledge base and the URL to the section where your documentation will be published.
The second one includes the path to your assemblies and XML files with the documenation.
All properties are well commented. Here is an example of the configuration file (we suppose there that the team's ID is myteam and the knowledge base's ID is mykb):
{
"aistant": {
"username": "myteam-clientapp@aistant.com",
"password": "qwerty!12345",
"team": "myteam",
"addVersion": false,
"publish": true,
"kb": "mykb",
"section": {
"uri": "mylib-api-reference",
"title": "My Library API reference"
}
},
"source": {
"mode":"csharp",
"path": "C:\\Projects\\MyLibrary\\dist",
"filter": {
"assembly": "^MyCompany\\.MyLibrary",
"namespace": ""
}
}
}
The latest (filter) section of the config file contains a regular expression which filters necessary assemblies and/or namespaces
The filter from the example above means that AistDoc takes all assemblies started with MyCompany.MyLibrary and will generate the docs for all classes with any namespace within those files.
Generating and uploading the documentation
When the configuration file is ready you can start generation of the documents and uploading them to Aistant with the followng command:
aistdoc publish --config:<Config file path>
For example:
aistdoc publish --config:mylib.json
Generating the documentation localy
AistDoc has an option which allows you to generate all articles locally - just to check how it works and how many documents you will have totally.
For this case you can fill only source section in your configuration file and add --output option to the command:
aistdoc publish --config:mylib.json --output:docs
