Table of Contents
Tip

The docs as explained here are used in multiple projects, but documented only once for better maintenance. When applying this to other projects, remember that some things such as the name, repository, or paths are a bit different.

Introduction to Documentation

Here we'll explain how the documentation works, with all the magic in it.

The Basics

Tip

These docs project generates the documentation using docfx. So for the most part, you'll want to read the docfx documentation to understand how it works.

The Source Code

This project has a src folder containing...

  1. markdown files in /pages for standalone docs pages
  2. markdown files in /apidoc for merging with XML-docs in the source of Oqtane
  3. various YAML files (.yml) which describe the navigation structure
  4. Solution (.sln) and project (.csproj) files to build the documentation
  5. docfx configurations (docfx.json and filterConfig.yml)
  6. various json configs so it also works in VS-Code

It also requires the Oqtane.Framework project to be in a sibling folder (see setup)

The Build Process

flowchart TD
    CS["C# Source <br><code>../some-project</code>"] -->|⚙️Compiler| XD
    XD["Xml Docs<br>(temp)"] --> MD["Merged API Docs<br>(temp)"]
    DM[Docs Mixins<br>~/apidocs] --> MD
    CONTENT[Content/Articles<br>~/pages] --> Docs[Docs HTML<br>../docs/]
    ASS[Assets/Images<br>**/assets] --> Docs
    MD --> Docs
    TOC["TOC Files<br>**/toc.yml"] --> TOCG
    Docs -->|generate| TOCG["Various TOCs<br>(Tables of Contents)"]

When you build this project, it will

  1. Compile the Source Code
  2. Extract the XML documentation from the XmlDocs and generate YAML and markdown files
  3. Merge the generated files with the ones in this project
  4. Generate a ../docs folder with static HTML files that can be hosted anywhere
Note

To test the generated docs locally, you'll need to host the ../docs folder on a web server. This is because there are some absolute paths used in some JavaScripts for the TOC (table of contents) and search functionality.


Main Author

Daniel Mettler, @iJungleboy [MS MVP, Oqtane Core Team]

Content Management Expert, Chief Architect of 2sxc and cre8magic.
Forged in the jungles of Indonesia, lives in Switzerland , loves Oqtane 🩸 & 2sxc 💜.

LinkedIn | Discord: @iJungleboy | Twitter: @iJungleboy | Github: @iJungleboy

Edit this page