diff --git a/README.md b/README.md index 8f887f4..a520e31 100644 --- a/README.md +++ b/README.md @@ -95,21 +95,21 @@ If you use a different operating systems and a different methods of installation Running `dotnet docfx` runs both the `dotnet docfx metadata` command and the `dotnet docfx build` command in that order. Unless specified otherwise, `dotnet docfx` uses the `docfx.json` as its config file. -### `metadata` +### metadata The metadata command generates a .yml files containing metadata from the source code. These files contain information about class members, class inheritance, enum fields, etc. and \ comments from the source code. The input files for the `metadata` command are specified in `metadata.src` of the `docfx.json` file, and the output directory of the `metadata` command is specified in `metadata.dest` of the `docfx.json` file. -### `build` +### build The build command generates raw and view data models for each .yml file generated by the `metadata` command and uses those raw and view data models to populate a template with data. -The build process involves multiple steps. +The build process involves multiple steps: -1. Generates a raw data model from each .yml file -1. Uses template to generate view data model from the raw data model. To see the raw model, refer to the relevant command in the [Troubleshooting](#troubleshooting) section of this README.md. -1. Uses template to populate pages with data from the view data model. To see the view models, refer to the relevant command in the [Troubleshooting](#troubleshooting) section of this README.md. +1. Generates a raw data model from each .yml file. +1. Uses template to generate view data model from the raw data model. To see the raw model, refer to the relevant command in the [Troubleshooting](#troubleshooting) section of this readme. +1. Uses template to populate pages with data from the view data model. To see the view models, refer to the relevant command in the [Troubleshooting](#troubleshooting) section of this readme. -The user can hook into and modify the build process at steps 2 and 3 by editing the template. +The user can hook into and modify the build process at each of these steps by editing the template. All of the files involved in defining the template are specified in the `build.template` of the `docfx.json` file. The order in which the templates are defined matters. If the templates contain files with conflicting names, the template specified later overrides the template specified earlier with its conflicting file(s). This is helpful because it enables building custom templates on top of other templates. To see the docfx `default` and `modern` templates, refer to the relevant command in the [Troubleshooting](#troubleshooting) section of this README.md. @@ -121,15 +121,15 @@ The docfx template system comprises of two primary components: the `.js` preproc ### [Preprocessor](https://dotnet.github.io/docfx/tutorial/intro_template.html#preprocessor) -There are two functions that are called during the preprocessor step. They are `getOptions()` and `transform()`. They are called for every .yml file generated by the `metadata` command. `getOptions()` provides the user with the opportunity to modify the raw data file. `transform()` provides the user with the opportunity to modify the view data dile. +There are two functions that are called during the preprocessor step. They are `getOptions()` and `transform()`. They are called for every .yml file generated by the `metadata` command. `getOptions()` provides the user with the opportunity to modify the raw data model. `transform()` provides the user with the opportunity to modify the view data model. -When `getOptions()` is called for a given .yml file, setting the `isShared` flag as `true` incorporates the raw data model for every other .yml file into the raw data model of the .yml file whose `isShared` flag as `true`. This provides access to other classes', enums', namespaces', etc. metadata when `transform()` is called. This flag greatly expands the possibilities so it's worth explicitly mentioning. +When `getOptions()` is called for a given .yml file, setting the `isShared` flag as `true` incorporates the raw data model for every other .yml file into the raw data model of the .yml file whose `isShared` flag as `true`. This provides access to other classes', enums', namespaces', etc. metadata when `transform()` is called. This flag greatly expands the possibilities so it's worth explicitly mentioning. Setting the `isShared` flag as `true` would correspond with hooking into step 1 of the [build](#build) process. -The `transform()` function transforms the raw data model to the view data model. Through this transformation process, the user can add logic to the template and process the source code's metadata. The default `transform()` function can be overwritten by writing your own `transform()` function in `.overwrite.js` or can be extended by writing your own `preTransform` and `postTransform` in the `.extension.js` file. +The `transform()` function transforms the raw data model to the view data model. Through this transformation process, the user can add logic to the template and process the source code's metadata. The default `transform()` function can be overwritten by writing your own `transform()` function in `.overwrite.js` or can be extended by writing your own `preTransform` and `postTransform` in the `.extension.js` file. Extending or overwriting the `transform()` function would correspond with hooking into step 2 of the [build](#build) process. ### [Renderer](https://dotnet.github.io/docfx/tutorial/intro_template.html#renderer) -The renderer step utilizes [mustache](http://mustache.github.io/) syntax to create a template which is populated with data from the view model data. +The renderer step utilizes [mustache](http://mustache.github.io/) syntax to create a template which is populated with data from the view model data. Writing custom `.tmpl` files would correspond with hooking into step 3 of the [build](#build) process. ## Troubleshooting