From f5ed95e8dc4980edf6930bd8e413c25c4e59d5ac Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Fri, 24 Apr 2020 12:59:29 -0700 Subject: [PATCH 1/3] Clarify exclude/include behavior in README --- README.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 63ec33d61c..18f0836b56 100644 --- a/README.md +++ b/README.md @@ -120,18 +120,23 @@ dartdoc: - tool-error ``` +#### dartdoc_options.yaml fields + +In general, **paths are relative** to the directory the `dartdoc_options.yaml` the option is defined in +and should be specified as POSIX paths. Dartdoc will convert POSIX paths automatically on Windows. Unrecognized options will be ignored. Supported options: * **categories**: More details for each category/topic. For topics you'd like to document, specify the markdown file with `markdown:` to use for the category page. Optionally, rename the - category from the source code into a display name with 'name:'. If there is no matching category + category from the source code into a display name with `name:`. If there is no matching category defined in dartdoc_options.yaml, those declared categories in the source code will be invisible. * **categoryOrder**: Specify the order of topics for display in the sidebar and the package page. * **examplePathPrefix**: Specify the location of the example directory for resolving `@example` directives. * **exclude**: Specify a list of library names to avoid generating docs for, - overriding any specified in include. + overriding any specified in include. All libraries listed must be local to this package, unlike + the command line `--exclude`. * **errors**: Specify warnings to be treated as errors. See the lists of valid warnings in the command line help for `--errors`, `--warnings`, and `--ignore`. * **favicon**: A path to a favicon for the generated docs. @@ -140,21 +145,23 @@ Unrecognized options will be ignored. Supported options: * **header**: A list of paths to header files containing HTML text. * **ignore**: Specify warnings to be completely ignored. See the lists of valid warnings in the command line help for `--errors`, `--warnings`, and `--ignore`. - * **include**: Specify a list of library names to generate docs for, ignoring all others. + * **include**: Specify a list of library names to generate docs for, ignoring all others. All libraries + listed must be local to this package (unlike the command line `--include`). * **includeExternal**: Specify a list of library filenames to add to the list of documented libraries. * **linkTo**: For other packages depending on this one, if this map is defined those packages will use the settings here to control how hyperlinks to the package are generated. - This will override the default for packages hosted on pub.dev. + This will override the default for packages hosted on [pub.dev](https://pub.dev) and + [api.flutter.dev](https://api.flutter.dev). * **url**: A string indicating the base URL for documentation of this package. Ordinarily - you do not need to set this in the package: consider --link-to-hosted and - --link-to-sdks instead of this option if you need to build your own website with + you do not need to set this in the package: consider `--link-to-hosted` and + `--link-to-sdks` instead of this option if you need to build your own website with dartdoc. The following strings will be substituted in to complete the URL: * `%b%`: The branch as indicated by text in the version. 2.0.0-dev.3 is branch "dev". No branch is considered to be "stable". - * `%n%`: The name of this package, as defined in pubspec.yaml. - * `%v%`: The version of this package as defined in pubspec.yaml. + * `%n%`: The name of this package, as defined in `pubspec.yaml`. + * `%v%`: The version of this package as defined in `pubspec.yaml`. * **linkToSource**: Generate links to a source code repository based on given templates and revision information. * **excludes**: A list of directories to exclude from processing source links. @@ -171,9 +178,6 @@ Unrecognized options will be ignored. Supported options: * **warnings**: Specify otherwise ignored or set-to-error warnings to simply warn. See the lists of valid warnings in the command line help for `--errors`, `--warnings`, and `--ignore`. -In general, paths are relative to the directory the dartdoc_options.yaml the option is defined in -and should be specified as POSIX paths. Dartdoc will convert POSIX paths automatically on Windows. - Unsupported and experimental options: * **ambiguousReexportScorerMinConfidence**: The ambiguous reexport scorer will emit a warning if From f72044418071012c764dec531d13ba6732d29c75 Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Fri, 24 Apr 2020 13:33:21 -0700 Subject: [PATCH 2/3] Grammar adjustment --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 18f0836b56..3cc8c51402 100644 --- a/README.md +++ b/README.md @@ -122,8 +122,8 @@ dartdoc: #### dartdoc_options.yaml fields -In general, **paths are relative** to the directory the `dartdoc_options.yaml` the option is defined in -and should be specified as POSIX paths. Dartdoc will convert POSIX paths automatically on Windows. +In general, **paths are relative** to the directory of the `dartdoc_options.yaml` file the option is defined +in and should be specified as POSIX paths. Dartdoc will convert POSIX paths automatically on Windows. Unrecognized options will be ignored. Supported options: * **categories**: More details for each category/topic. For topics you'd like to document, specify From 899956e05e39426c9bc477eb482cd454e0223df6 Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Fri, 24 Apr 2020 13:37:27 -0700 Subject: [PATCH 3/3] Actually fix it. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3cc8c51402..819d8ea550 100644 --- a/README.md +++ b/README.md @@ -122,8 +122,8 @@ dartdoc: #### dartdoc_options.yaml fields -In general, **paths are relative** to the directory of the `dartdoc_options.yaml` file the option is defined -in and should be specified as POSIX paths. Dartdoc will convert POSIX paths automatically on Windows. +In general, **paths are relative** to the directory of the `dartdoc_options.yaml` file in which the option +is defined, and should be specified as POSIX paths. Dartdoc will convert POSIX paths automatically on Windows. Unrecognized options will be ignored. Supported options: * **categories**: More details for each category/topic. For topics you'd like to document, specify