34 Install XML Documentation on GitHub Pages

This procedure allows you to create a GitHub page for your project, generate html documentation from the XML (/// summary) documentation, then upload your documentation to your GitHub page.

1. Create the docs folder in your GitHub repository

   • On the main page of your repository, click on new file
   • In the text field for the file name, type docs/ (note the slash at the end)
   • Name your file .gitkeep
   • Click Commit new file.

2. Create GitHub Pages for your project

   • On your Github repository, go to Settings
   • Scroll down the page until your reach the section GitHub Pages
   • Select "master branch /docs/folder" then click save
   • You may also select a theme for your page
   • Next to the GitHub Pages, the link to your GitHub pages is located is shown (i.e. https://mkfares.github.io/SchoolWebApp/index.html)
   • Browse to that link to check the creation of the page

3. Install docfx.console using NuGet Package

   • Right click on your project in Visual Studio (not solution)
   • Select Manage NuGet Packages
   • Select Browse on NuGet Window
   • Search for docx.console package (not docfx)
   • Select the package then install it

4. Generate html documentation in your visual studio project

   • Clean your solution using Build > Clean Solution
   • Build your solution using Build > Build Solution
   • Click on "Show All Files" icon located on the top of the Solution Explorer Window
   • You should see a folder named _site where the generated documentation is located

5. Copy the documentation in the docs folder

   • Right click on the project name (not solution) in solution Explorer
   • Select Open Folder in File Explorer
   • Right click on _site folder and select Copy
   • Go one level up in your directory level (e.g. to the folder that contains the sln file)
   • Delete the folder docs if it already exists
   • Paste the _site folder
   • Rename the pasted folder _site to docs

6. Upload changes to Github

   • Commit your changes in Team Explorer
   • Sync your local repo to your GitHub repo
   • Go to your GitHub pages (i.e. https://mkfares.github.io/SchoolWebApp/index.html)
   • Click on API Documentation located on the top menu to browse your documentation.

7. Edit the XML Documentation

   • In case you add or modify the xml documentation in your project, your need to redo the steps 4, 5, and 6.

8. References:

   GitHub Pages

   GitHub Pages Basics

   docfx Nuget Package

   XML documentation guide