diff --git a/ACKNOWLEDGEMENTS.txt b/ACKNOWLEDGEMENTS.txt index efc28c8..fca66d8 100644 --- a/ACKNOWLEDGEMENTS.txt +++ b/ACKNOWLEDGEMENTS.txt @@ -8,6 +8,7 @@ dependencies: * Apache Commons IO * Apache Commons Lang 3 * Apache Commons Text +* Apache Velocity * ClassGraph * Google GSON * Oracle Bean Validation API diff --git a/README.md b/README.md index 599d02b..20e9ba7 100644 --- a/README.md +++ b/README.md @@ -109,24 +109,25 @@ The command-line usage is as follows: ```text usage: apexdoc | @ - -p,--sfdx-project sfdx-project.json file - -s,--source input source directory - -u,--username Salesforce CLI username or alias - -i,--include-org-types whether org-only types should be included in - generated ApexDoc when the '-u/--username' - option is specified - -x,--exclude exclude directory - -o,--output output directory - -v,--visibility minimum visibility for included declarations; - one of private, protected, public, or global - (default protected) - -n,--namespace namespace - -nn,--no-namespace don't use the namespace from sfdx-project.json - -t,--title window title - -f,--overview overview HTML file - -c,--css custom stylesheet file - -h,--help show usage details - -version,--version show version information + -p,--sfdx-project sfdx-project.json file + -s,--source input source directory + -u,--username Salesforce CLI username or alias + -i,--include-org-types whether org-only types should be included in + generated ApexDoc when the '-u/--username' + option is specified + -x,--exclude exclude directory + -o,--output output directory + -v,--visibility minimum visibility for included declarations; + one of private, protected, public, or global + (default protected) + -n,--namespace namespace + -nn,--no-namespace don't use the namespace from sfdx-project.json + -ct,--custom-templates custom Velocity templates directory + -t,--title window title + -f,--overview overview HTML file + -c,--css custom stylesheet file + -h,--help show usage details + -version,--version show version information ``` As indicated, command-line options can be specified explicitly or as the contents of an [options file](#options-file). @@ -194,6 +195,23 @@ You can control whether a namespace is used for documented declarations using th * If the `sfdx-project.json` file contains a `namespace` property and the namespace should _not_ be used, the `-nn/-no-namespace` argument can be used to disable namespace processing. * If no `sfdx-project.json` file is specified, or if a different namespace than the one in that file should be used, the `-n/--namespace` argument can be used to specify a namespace value explicitly. +### Custom Velocity templates + +IcApexDoc generates HTML output files using the following [Apache Velocity](https://velocity.apache.org/) templates: + +* `headInclude.vm` - Included by all default page templates to provide the `...` portion of the resulting HTML files. This specifies the page title and includes the correct CSS file. +* `bodyHeaderInclude.vm` - Included by all default page templates to provide the header and top navigation sections of the resulting HTML files. +* `indexPage.vm` - Used to generate the main and top-level declaration type-specific index pages. +* `declarationPage.vm` - Used to generate the top-level declaration-specific pages. + +The default templates are included for reference in the distribution's `templates` directory, though be aware that they are read from the classpath at runtime, so changes to those files will not have any effect. It is possible to provide one or more custom templates using the `-ct/--custom-templates` argument: + +```text +apexdoc -p sfdx-project.json -o apexdoc -ct apexdoc_templates +``` + +The default templates should be used as a starting point when authoring custom templates, and the [Apache Velocity User Guide](https://velocity.apache.org/engine/1.7/user-guide.html) may also prove useful. Note that if a given template is not found in the custom templates directory, the corresponding default template is used. As a result, it is only necessary to add customized templates to the specified directory. + ### Project title You can specify the title of the project explicitly using the `-t/--title` argument. If unspecified and an `sfdx-project.json` file containing a `name` property is specified, that value is used as the project title. Otherwise the default value of `ApexDoc` is used. diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 0acc104..47af6c1 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -1,9 +1,14 @@ # Release Notes +* [1.0.0.4](#1004) * [1.0.0.3](#1003) * [1.0.0.2](#1002) * [1.0.0.1](#1001) +## [1.0.0.4](https://github.com/SCWells72/IcApexDoc/releases/tag/1.0.0.4) + +* [Issue 9](https://github.com/SCWells72/IcApexDoc/issues/9) - IcApexDoc now uses [Apache Velocity](https://velocity.apache.org/) templates to generate all HTML output files, and it is possible to provide custom templates via the `-ct/--custom-templates` argument. For more information, see [Custom Velocity templates](README.md#custom-velocity-templates). + ## [1.0.0.3](https://github.com/SCWells72/IcApexDoc/releases/tag/1.0.0.3) * [Issue 3](https://github.com/SCWells72/IcApexDoc/issues/3) - IcApexDoc now performs [full semantic validation](README.md#validation) of ApexDoc, reporting issues, omissions, etc., about ApexDoc comments and their respective Apex declarations. Validation rules are fully configurable via a [JSON options file](README.md#validator-options-file).