This template is based heavily on What nobody tells you about documentation. In docsSrc folder you'll see a similar structure to what is described below:
- Tutorials
- is learning-oriented
- allows the newcomer to get started
- is a lesson
- Analogy: teaching a small child how to cook
- How-To Guides
- is goal-oriented
- shows how to solve a specific problem
- is a series of steps
- Analogy: a recipe in a cookery book
- Explanation
- is understanding-oriented
- explains
- provides background and context
- Analogy: an article on culinary social history
- Reference
- is information-oriented
- describes the machinery
- is accurate and complete
- Analogy: a reference encyclopedia article
The folders in docsSrc are:
content- custom css, javascript, and similar go here.Explanations- A content section as defined above.files- extra files like screenshots, images, videos.How_Tos- A content section as defined above.Tutorials- A content section as defined above.index.md- The entry page to your documentation
The navbar is generated by the folders in docsSrc, excluding content and files folders. Looking at the example we can the navbar containing:
Api ReferencesExplanationsHow TosTutorials
The odd one not generated from the convention of your folders in docsSrc is Api References. This is generated by the XML Doc Comments in your libraries under the src folder.
USAGE: docsTool [--help] [<subcommand> [<options>]]
SUBCOMMANDS:
watch <options> Builds the docs, serves the content, and watches for changes to the content.
build <options> Builds the docs
Use 'docsTool <subcommand> --help' for additional information.
Builds the docs
USAGE: docsTool build [--help] [--sitebaseurl <string>] [--projectglob <string>] [--docsoutputdirectory <string>] [--docssourcedirectory <string>] [--githubrepourl <string>] [--projectname <string>]
[--releaseversion <string>]
OPTIONS:
--sitebaseurl <string>
The public site's base url.
--projectglob <string>
The glob for the dlls to generate API documentation
--docsoutputdirectory <string>
The docs output directory.
--docssourcedirectory <string>
The docs source directory.
--githubrepourl <string>
The GitHub repository url.
--projectname <string>
The project name.
--releaseversion <string>
The project's Release Version name.
--help display this list of options.
Builds the docs, serves the content, and watches for changes to the content.
USAGE: docsTool watch [--help] [--projectglob <string>] [--docsoutputdirectory <string>] [--docssourcedirectory <string>] [--githubrepourl <string>] [--projectname <string>] [--releaseversion <string>]
OPTIONS:
--projectglob <string>
The glob for the dlls to generate API documentation.
--docsoutputdirectory <string>
The docs output directory.
--docssourcedirectory <string>
The docs source directory.
--githubrepourl <string>
The GitHub repository url.
--projectname <string>
The project name.
--releaseversion <string>
The project's Release Version name.
--help display this list of options.