Docs Recipe

[daveaglick]

A new recipe that generates API documentation from source code as well as textual content from Markdown/Razor files. Some requirements:

• Text content needs to be able to link to API docs - need to figure how to indicate API links
• Searching for both API docs and text content
• Text content should allow two levels of nesting, - top level and sub pages
• Top-level headings in both text content and API docs should be presented as floatable sidebar for quick jumping
• Auto-generate edit on GitHub links
• Support for "sidecar" Markdown for API docs (this might already be supported in Roslyn)
• Consider generating class diagrams using either MSAGL (pre-generated) or Mermaid (client-generated)
• How to support multiple versions? First thought is to drive separate generations from a build tool like Cake. For example, to generate for tags in a repo, Cake would check out each tag, run the doc build, place output in a separate folder. We'd need to provide a set of top-level builds to each individual build so they can generate consistent links across versions - this could be a JSON or YAML file and maybe the build tool could generate before running doc builds.

When done, consider bringing some features back to Blog Recipe like searching, multi-level content pages, header sidebars, etc.

[daveaglick]

Initial thoughts on theme:

• Really like the "feel" of new .NET Core docs and VS Code docs
• Base on SB Admin 2 template
• Look at PrettyDocs to see how they do the sticky nav for the right side

[gep13]

@daveaglick with regard to this:

Text content should allow two levels of nesting, - top level and sub pages

We actually have an open issue on the website to include an additional layer of nesting:

https://github.com/cake-build/website/issues/41

Is this something that will be configurable?

[daveaglick]

@gep13 Yep! I went ahead and made the nesting depth arbitrary so you'll be able to add as many levels as needed.

FWIW, it's also file-driven so you won't need a ToC XML file like you've been using. To add extra items you just add a file, and nesting is just a folder.

[gep13]

Sweet! 👍

[jairbubbles]

For "Edit in GitHub link" it would be great if we can customize the link and the name / icon. For instance "Edit in Gitlab".

[daveaglick]

@jairbubbles Totally agree. Planning to have user supply the base URL and then just append the Markdown and/or code relative path to that, so host could be anything.

[daveaglick]

[gep13]

WOO HOO!