Skip to content

Clarify exclude/include behavior in README #2193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 24, 2020
Merged

Clarify exclude/include behavior in README #2193

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f5ed95e
Clarify exclude/include behavior in README
jcollins-g Apr 24, 2020
f720444
Grammar adjustment
jcollins-g Apr 24, 2020
899956e
Actually fix it.
jcollins-g Apr 24, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 15 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The grammar here is hard to parse. Maybe

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

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.
Expand All @@ -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.
Expand All @@ -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
Expand Down