Create your project documentation
Introduction
This article will guide you through the process of creating a documentation for your C# project using the tool DocFX. Documentation is key to help user understand how to use the tools you create. It is also a good way to show the quality of your work.
Prerequisites
- Having looked at the project from the Introduction section
- .NET 6.0 or later
Install DocFX
Ensure that you have dotnet (C#) installed by running:
dotnet --version
To install docfx, or update it, open any terminal and run the following command:
dotnet tool update -g docfx
Setup workspace
As we are taking back the Introduction project
to set the example, here is the file structure before generating the documentation:
Example_project <-- root
└───MyApp
├───bin
├───MyApp.csproj
└───Program.cs
Open a terminal to the root of the project(the end of your path should be Example_project/
), and run the following command:
docfx init -y -o documentation
Now you should have a new folder called "documentation" in the root of your project. Your folder structure should look like this (files are specified with the dots):
Example_project <-- root
├───documentation
│ ├───docs
│ │ ├───getting-started.md
│ │ ├───introduction.md
│ │ └───toc.yml
│ ├───docfx.json
│ ├───index.md
│ └───toc.yml
└───MyApp
├───bin
├───MyApp.csproj
└───Program.cs
Here should be the default content of docfx.json
:
{
"metadata": [
{
"src": [
{
"src": "../src",
"files": ["**/*.csproj"]
}
],
"dest": "api"
}
],
"build": {
"content": [
{
"files": ["**/*.{md,yml}"],
"exclude": ["_site/**"]
}
],
"resource": [
{
"files": ["img/**"]
}
],
"output": "_site",
"template": ["default", "modern"],
"globalMetadata": {
"_appName": "",
"_appTitle": "",
"_enableSearch": true,
"pdf": true
}
}
}
For a more convenient display, features and to target to the project, I recommend you to update the file to the version below. For more information, see the official documentation of the references tags.
{
"metadata": [
{
"src": [
{
"src": "../MyApp",
"files": ["**/*.csproj"]
}
],
"dest": "api"
}
],
"build": {
"content": [
{
"files": ["**/*.{md,yml}"],
"exclude": ["_site/**"]
}
],
"output": "_site",
"resource": ["assets/**"],
"template": ["default", "modern"],
"keepFileLink": false,
"disableGitFeatures": false,
"globalMetadata": {
"_appName": "MyApp",
"_appTitle": "MyApp",
"_appFooter": "Copyright (C) 2024 Your Name",
"_enableSearch": true,
"_disableContribution": true,
"pdf": true
}
}
}
Note
You may want to select the channel of the documentation you want to generate. For example, if you want to generate the documentation for the Debug or Release version only. Feel free to update files
to Debug or Release and TargetFramework
to your dotnet version(available in the MyApp.csproj
).
...
"metadata": [
{
"src": [
{
"src": "../MyApp",
"files": ["**/bin/Debug/**.dll"]
}
],
"dest": "api",
"properties": {
"TargetFramework": "net8.0"
}
}
],
...
Do not forget to update your compiled files using the dotnet build
command:
Preview your doc
Now, back on your terminal from the root, run the following command:
docfx build documentation/docfx.json --serve
The output should end like this:
...
Serving ".../MyApp/documentation/_site" on http://localhost:8080. Press Ctrl+C to shut down.
Your documentation is now available on http://localhost:8080 if you want to see the preview on localhost.
Customize your doc
Add sections
By default, the only sections available are Docs
and Api Documentation
. You may want to add more sections to your documentation. To do so, you will have to do fe steps:
- Add a new folder in the
documentation
folder. For example,articles
. - Inside
articles
, add aindex.md
file and atoc.yml
file.
Here is an example of the index.md
file:
# Articles
This is the articles section. You can add articles to explain how to use your library.
Here is an example of the toc.yml
file:
items:
- name: Articles
href: index.md
Note
We added the items
tag to the toc.yml
file. This is the root of the table of contents and will remove the error Incorrect Type. Expected "TOC"
.
- Now, we need to update the
toc.yml
file in thedocumentation
folder to add the new section. I recommend adding a homepage mention (will be the landing page when the section is clicked). Here is an example of thetoc.yml
file:
items:
- name: Docs
href: docs/
- name: API
href: api/
- name: Articles
href: articles/
homepage: articles/index.md
Add pages
Now that you know how to create new sections, to add pages you may just add markdown files to the sections folder, and add them to the toc.yml
file. Here is an example of the toc.yml
file:
items:
- name: Getting Started
href: index.md
- name: How to use the library
href: how_to_use.md
- name: How to publish your work
href: how_to_publish.md
However you may also be able to create collapsible menu in the toc.yml
file. Here is an example of the toc.yml
file:
items:
- name: Getting Started
href: index.md
- name: Advanced
items:
- name: How to use the library
href: how_to_use.md
- name: How to publish your work
href: how_to_publish.md
Or use another style and display the category name, and the pages without being collapsible:
items:
- name: Getting Started
href: index.md
- name: Other pages
href: how_to_use.md
href: how_to_publish.md
Markdown features support
DocFX supports a lot of markdown features. All of them are listed in the official documentation.
Logo & favicon
To add a logo or favicon to your documentation, start by adding them into the assets folder (if you have not, create it in the documentation
folder). Then, update the docfx.json
file to add the logo
and favicon
tags. Here is an example:
...
"build": {
...
"resource": ["assets/**"],
"globalMetadata": {
...
"_appLogoPath": "assets/logo.jpg",
"_appFaviconPath": "assets/favicon.ico",
...
}
...
}
For both I recommend you using svg files so that the logo and favicon are scalable and will not lose quality.
Code documentation
Coding in C#, you may be aware of the use of the ///
comments to document your code. This is a good practice to help other developers understand your code. DocFX will take these comments into account to generate accurate documentation. Please refer to the official documentation for more information.
For docfx to support these metadata, ensure that a documentation file is generated correctly. Add this line to your "**.csproj" file, inside the "PropertyGroup" tag:
<GenerateDocumentationFile>true</GenerateDocumentationFile>
Here is a little troubleshooting if you have an error while building the documentation:
- Check the version of your dotnet.
- Update docfx.
- Check the
docfx.json
path to your project (e.g.../MyApp
). - Check if you have well put a
namespace
in your file. - Your
program.cs
will not be used in the documentation, so you will need to have at least on more class. Here is a quick example to copy/paste in a new file:
namespace MyApp;
/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
public class Point
{
private int x;
private int y;
/// <summary>
/// Initializes a new instance of the <c>Point</c> class.
/// </summary>
public Point(int x, int y)
{
this.x = x;
this.y = y;
}
/// <summary>
/// Gets the x-coordinate of the point.
/// </summary>
public int X
{
get { return x; }
}
/// <summary>
/// Gets the y-coordinate of the point.
/// </summary>
public int Y
{
get { return y; }
}
/// <summary>
/// Returns a string that represents the current object.
/// </summary>
public override string ToString()
{
return $"({x}, {y})";
}
}
Now your documentation is ready to be generated in the section API
in the generated site (you may change all sections names in your toc.yml
file at the root of your documentation folder).
Deploy the doc
GitHub Pages
GitHub provides a service called GitHub Pages that allows you to host static websites directly from your repository. We will need to setup few things before deploying the documentation.
First of all, go to your repository settings, then to the "Pages" section. Select "Deploy from branch", then select the branch "gh-pages" branch and the root folder. Then click on "Save". If you do not have a "gh-pages" branch, you will have to create one (it is better if it is empty at the beginning but it is not mandatory).
Deployment
Then, you will have to create a new folder called .github
at the root of your project. Inside this folder, create a new folder called workflows
. Inside this folder, create a new file called deploy_docs.yml
. This file will contain the workflow to generate and deploy the documentation on GitHub Pages.
Here is an example of the deploy_docs.yml
file:
name: Deploy docs
on:
push:
branches:
- main
jobs:
publish-docs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Dotnet Setup
uses: actions/setup-dotnet@v3
with:
dotnet-version: 8.x
- run: dotnet tool update -g docfx
- run: docfx documentation/docfx.json
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: docs/_site
Push the changes and go to the "Actions" section of your repository. You should see a new workflow called "Deploy docs". Click on it to see the logs. If everything went well, you should see a "Deployed" message at the end of the logs.
Now, on every push on the main branch, the documentation will be generated and deployed on GitHub Pages.
Note
In your github repository description, click on "Edit" then for the url select the "GitHub Pages" url option. So that your documentation is directly accessible from your repository.
Sources
- DocFX documentation
- Useful but not official documentation
- C# documentation comments
- DocFX markdown support
Have a question, give a feedback or found a bug? Feel free to open an issue or start a discussion on the GitHub repository.