infer/docs/README.md

Build API documentation

The API documentation is generated by using DocFX. The last version of the API documentation is in the apiguide/ folder of gh-pages branch. If you want to create a new version of the API documentation:

1. Commit your changes before start the build process.

2. Use TestApp to run InferenceEngine.ShowFactorManager(true). Move the generated factorTable.html file to a temporary folder.

3. Run the powershell script docs/_build/makeApiDocs.ps1. makeApiDocs.ps1 script should create the folder apiguide-tmp/ with the API documentation.

   makeApiDocs.ps1 script should:

   • copy a part of repository to the temporary folder InferNet_Copy_Temp,
   • build PrepareSource.csproj project,
   • run PrepareSource.exe for the InferNet_Copy_Temp folder,
   • install NuGet package docfx.console,
   • run docfx,
   • remove temporary folder InferNet_Copy_Temp,
   • switch to gh-pages,
   • create commit with the new changes.

4. Move the generated factorTable.html to the _includes folder.

5. Push new changes to the gh-pages.

Documenting Factors

Infer.NET provides tool to automatically generate description text for factor classes, i.e. classes marked with [FactorMethod] attribute. Generated descriptions are written to src/Runtime/Factors/FactorDocs.xml file and referenced using <include> tags in source code triple comments.

It is important to have full and correct description of all factors, so when you change existing factor or add new one, please follow steps below.

1. Add triple comment

   /// <include file='FactorDocs.xml' path='factor_docs/message_op_class[@name="FactorClassName"]/doc/*'/>

   before newly created factor classes. Replace FactorClassName with actual class name without namespace.

2. Run BuildFactorDoc project from Microsoft Visual Studio or .NET Core CLI.

3. Commit updated src/Runtime/Factors/FactorDocs.xml.