Documentation–part 6


This is a part of the series where about how I made the WebAPI2CLI - Execute ASP.NET Core WebAPI from Command Line
Source code on
1WebAPI2CLI - Description
2WebAPI2CLI- Organization
3WebAPI2CLI - implementing
4WebAPI2CLI - tests
5WebAPI2CLI - Devops and CI/CD
6WebAPI2CLI - documentation
7WebAPI2CLI - Conclusions
8WebAPI2CLI - Zip application

I need 2 types of documentation:

1. For let people know how to use

2. For the programmers – to understand what the classes are doing


For the first point, documentation to use

a. Github has already the file that shows details for the repository . What I need is something more- i.e. detailed instruction, FAQ, Author.

b. Github has made easy to make an online site  -by having the docs folder public with his own address. For example, from I can have . Now , the problem is how to concatenate those and put back to site

c. GitHub has also the concept of Actions –i.e.  DevOps integrated.


So –what I have done is to use pandoc , compile all the .md files into html ( and pdf ) and push modifications back to the site.


– uses: actions/checkout@v2

– run: |

echo generate help file

mkdir output

git pull

– name: generate html

uses: docker://pandoc/latex:2.9

with: # needs a README in your repo root!

#args: “–standalone –output=output/README.html”

args: “ docs/ docs/ docs/ –standalone -f gfm -t html  –toc -o output/output.html –metadata title=WebAPI2CLI”

– name: generate pdf

uses: docker://pandoc/latex:2.9

with: # needs a README in your repo root!

#args: “–standalone –output=output/README.html”

args: “ docs/ docs/ docs/ –standalone -f gfm -t pdf  –toc -o output/output.pdf –metadata title=WebAPI2CLI”

– run: |

cp ./output/output.html ./docs/index.html

cp ./output/output.pdf ./docs/Web2CLI.pdf

rm -rf ./output


You can see the results at and the sources at

For the second point, generating documentation from XML Comments in C#

I need some free .NET tool to do this. I did not found. I have hesitated also between ( an old friend, but cumbersome ) and ( a new friend, but still cumbersome)

What I have done is to download docfx, add to the site, follow instructions , modify some of the templates , resist temptation to put everything into docfx ( he kinda want to be all inclusive)


# The type of runner that the job will run on

runs-on: windows-latest


# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it

– uses: actions/checkout@v2

– name: run documentation

run: |


rem git config –local “”

rem git config –local “GitHub Action”

rem git commit -m “generate documentation sources” -a –allow-empty

shell: cmd

– name: Push changes

uses: ad-m/github-push-action@master


github_token: ${{ secrets.GITHUB_TOKEN }}

You can see the results at  and sources at