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.

• 🌴 2sxc: Docs Repo, Docs Live
• 🩸 Oqtane: Docs Repo, Docs Live
• ♾️ cre8magic: Docs Repo, Docs Live

C# Code Docs Generation

Warning

This is a technical documentation about how the documentation system works. It helps the core team understand how to maintain and enhance the documentation system.

It's not meant for most contributors, as it's too technical.

C# Code Generation and Merging

This process is configured in docfx.json. It is quite tricky as small changes can have big effects. Important to know:

1. All /pages/**/*.md will be normal output pages

2. All C# code from the specified .csproj projects will be converted to markdown in the git-excluded /api-generated folder...

3. ...and then merged with the /api-docs folder which is manually maintained. This is needed because auto-generated code cannot have namespace descriptions, and sometimes we need much more complex docs for a specific class (which is also in the /api-docs folder).

4. The exact behavior is configured in the docfx.json file. Note that trivial changes can have big effects, so be careful. Example:

   1. a section { "src": "api", "files": ["**.yml"] } will create a different result than...

   2. a section { "files": ["api/**.yml"] }. Such details can cost you a lot of time.

5. We filter out _*.yml files as they should not create a page, but are instead used for !include statements.