Documentation–part 6
WebAPI2CLI
This is a part of the series where about how I made the WebAPI2CLI - Execute ASP.NET Core WebAPI from Command LineSource code on https://github.com/ignatandrei/webAPI2CLI/
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 readme.md 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 https://github.com/ignatandrei/webAPI2CLI/ I can have https://ignatandrei.github.io/WebAPI2CLI/ . 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.
See https://github.com/ignatandrei/WebAPI2CLI/blob/master/.github/workflows/main.yml
– 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 README.md”
args: “README.md docs/Demo.md docs/FAQ.md docs/Author.md –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 README.md”
args: “README.md docs/Demo.md docs/FAQ.md docs/Author.md –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 https://ignatandrei.github.io/WebAPI2CLI/ and the sources at https://github.com/ignatandrei/WebAPI2CLI/tree/master/docs
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 https://github.com/EWSoftware/SHFB ( an old friend, but cumbersome ) and https://github.com/dotnet/docfx/ ( 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)
docs_csharp:
# The type of runner that the job will run on
runs-on: windows-latest
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
– uses: actions/checkout@v2
– name: run documentation
run: |
DocumentationSources.bat
rem git config –local user.email “action@github.com”
rem git config –local user.name “GitHub Action”
rem git commit -m “generate documentation sources” -a –allow-empty
shell: cmd
– name: Push changes
uses: ad-m/github-push-action@master
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
You can see the results at https://ignatandrei.github.io/WebAPI2CLI/sitedocs/api/index.html and sources at https://github.com/ignatandrei/WebAPI2CLI/tree/master/docs/sitedocs
Leave a Reply