Contribute to documentation

1 Overview

Documentation is created using DocFx tool.
More information here.

You do not need to look too much at the DocFx official documentation as all steps you need to know are described below.

2 Implementation

2.1 The project Events.Docfx

Documentation project is stored in git repo Events.Docfx.

This is not a visual studio project or solution but a folder with all required files and sub-folders for generating a documentation web site.

You can use Visual Studio (open a folder) and integrated git, or any text editor with an integrated or external git controler.

Note: use only dev branch for the documentation. Only a git push on dev branch will trigger the deployment of a new documentation on web site https://oneisb-documentation-lab-wa.azurewebsites.net/ through the CI/CD.

2.2 Sources of documentation

The documentation is built from 2 sources:

  • General static documentation: files *.md (Markdown) located at the folders and sub-folders of project Events.Docfx;
  • Dynamic documentation generated automatically from source code of some other projects.

The documentation from source code is built from the dev branch of the git repo of the project to document. DocFx builds automatically a web page for each class (for C# code) with a documentation about all fields, properties, methods... DocFx uses the comments like

/// <summary>This is a documentation supporting markdown/mermaid format</summary>

before each item (class, field, property, method...) for building the documentation about the item.

The source code files to be added in the documentation are listed in the file docfx.json.

2.3 Markdown/Mermaid

Markdown format is used in:

  • files *.md of the project,
  • comments like <summary></summary> in the source code.

It allows many basic rendering like:

  • bold, italic
  • headers,
  • arrays,

emphasize

  • lists
    • sublists
  • ...
  • and of course, links.

Markdown can embed some Mermaid syntax, for displaying a large variety of complex diagrams.

3 How to document

3.1 Update a document

If you want to update one of the document, you can retreive it in the project in the corresponding folder.
You can also quickly access to it by clicking on the "Improve the document" link you will find on the docfx site on top of the table of content displayed on the right side of the screen.

3.2 Add a new sub-site

In the project, create a subfolder, containing files:

  • toc.md: the table of content: a map name=>file.md (the file must exist in the folder)
#[Overview](overview.md)
#[Skynet.CatalogConnector](skynet.catalogconnector.md)
#[Skynet.BillingConnector](skynet.billingconnector.md)
  • overview.md: the default page.

In file toc.yml (at the root), reference the new sub-site with a name, the sub-folder, the default page:

- name: My Sub Site
  href: MySubSite/
  homepage: MySubSite/overview.md

3.2 Add a new page

Create a new file *.md with some documentation.

In same folder, define the page in file toc.yml (table of content):

#[My New Page](MyNewPage.md)

3.3 Add a new NuGet Neo.Events.***

Docfx can generate documentation from source code. To do so, you have to:

  1. Clone your events.xxx repo on your local computer (at the same level as this solution folder).
  2. Add the events.xxx folder you want to parse in the docfx.json file (in the metadata/src part of the json file, you have to clone an existing definition and setup your own folder).
    this needs to be added in the group where "dest": "events/sourcecode" is declared.
	{
		"files": [ "**.cs", "**/**.cs" ],
		"src": "../Events.Ddi/Neo.Events.Ddi/Dto"
	}
  1. Rebuild your local website (launching the cleanAndRebuild.bat program)
  2. Test your documentation
  3. Check-in your changes
  4. Once done, you will have to update the release pipeline of the docfx project to collect your latests NuGet sources during CI/CD.
    Follow the chapter named "CI/CD your new source documentation"

3.4 Add a new team project with source code documentation

You can also add the documentation of your own project if you want to. You will have to follow more or less the same mechanism.

  1. Create your project folder
  2. Create an overview.md file where you put general documentation of your project
  3. Create a subfolder "sourcecode" where all the automatic documentation will be stored
  4. Edit the git.ignore file to add the sourcecode folder in the list of folder to ignore as this folder will be auto generated from code.
  5. Edit the docfx.json and add a new metadata bloc. This is needed to generate the documentation from your source code.
    note: You need to extract your project code before and place it at the same level as the Events.docfx folder (this is needed to allowed docfx to retreive your code and to extract the documentation).
{
	"src": [
	{
		"files": [
		"**.csproj"
		],
		"src": "../YourSolutionFolder/YourProject"
	}
	],
	"dest": "YourFolderInDocFx/SourceCode",
	"disableGitFeatures": false,
	"disableDefaultFilter": false
}
  1. Edit the docfx.json and add a new setting in the build/content/Files bloc. This is needed to publish all the files generated.
"YourFolderInDocFx/**/**.yml",
"YourFolderInDocFx/**.md"
  1. Add a toc.md in your new docfx folder and add the following lines
#Concepts
##[Overview](overview.md)
#[Documentation](sourcecode/toc.yml)
  1. Edit the toc.yml file located at the root of the docfx solution. This is needed to add a new tab definition for your team project.
- name: Your project name
  href: YourFolderInDocFx/
  homepage: YourFolderInDocFx/overview.md
  1. Test locally till you like it.
  2. check in your changes
  3. Edit the CI/CD as describe before in the "CI/CD your new source documentation" chapter.

If you have multiple modules (as OneISBilling for example), you can create multiple source code sub folders (one per project or solution). Please have a look on how OneISBilling is done.

3.5 CI/CD new documented source code

Once you have added the source code of a new project in the documentation (section 3.3 or 3.4), you want the CI/CD to trigger a new build of the documentation each time a change is pushed on the dev branch of the new project.

Go on http://arkadin.visualstudio.com/common.
Go in the release folder and edit the Events.DocFX pipeline.

The release project is in common.

You will have to add one artifact pointing on your project and solution.
Add artifact

Then you will have to activate the documentation generation when your code change by clicking on the ligthning icon. Add artifact

4 Local testing

4.1 Test syntax

Before building and testing locally the whole documentation (that can be long), you may want to test some pieces of markdown or mermaid syntax. You can use web site StackEdit in your browser:

  • copy/paste your code in the left panel,
  • check the result displayed in right panel.

There are some few differences between the result you can see and the one you will have in docfx. Carriage return are not displayed the same way. Sometimes, you will see distinct lines displayed on the same line (in docfx).
To avoid this, you must add </br> tag at the end of the lines.
DocFx is following the github markdown flavor described here.

4.2 Test whole documentation

4.2.1 Prerequisites

You must install docfx and mermaid on your computer to test the documentation from a command line running with administrator rights.

choco install docfx

If you don't have choco installed on your computer, you can retreive it here:https://chocolatey.org/install

yarn add mermaid

If you don't have yarn installed on your computer, you can retreive it here:https://yarnpkg.com/lang/fr/docs/install/#windows-stable

4.2.2 Get source code if needed

You need to get, on your local computer, the source code of the projects for which you want to check the documentation.
Project folder must be placed at the same level as folder Events.Docfx.

4.2.2 Test

Open a command prompt in folder Events.Docfx, then launch the cleanAndRebuild.bat program. This program will:

  • clean the local site,
  • rebuild all the documentation,
  • start a local web server on port 8080,
  • open the web documentation in your default browser.

4.2.3 Re-Test

If you have updated the files locally and want to see the result, you have to stop/restart the cleanAndRebuild.bat program:

  • press Ctrl+C, O, ENTER,
  • re-run cleanAndRebuild.bat;
  • sometimes you may have to force the refresh of web page in your browser (F5).

5 Resources