From 631e978662e156a70561a4b70470052303188bd0 Mon Sep 17 00:00:00 2001 From: Nick Fox Date: Thu, 29 Mar 2018 15:03:54 -0400 Subject: [PATCH] Add support for an "include" option * Added support for -i or -include which has the opposite behavior of the exclude flag * Updated file filtering to account for include flag * Updated README and documentation --- CHANGELOG.md | 5 ++++- README.md | 27 +++++++++++++++++---------- lib/jazzy/config.rb | 9 +++++++++ lib/jazzy/sourcekitten.rb | 26 ++++++++++++++++++++++++-- 4 files changed, 54 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 06b676661..40ca4f48c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,10 @@ ##### Enhancements -* None. +* Added the ability to limit documentation to certain files by passing in an + `-i`/`--include` argument. + [Nick Fox](https://github.com/nicholasffox) + [#949](https://github.com/realm/jazzy/issues/949) ##### Bug Fixes diff --git a/README.md b/README.md index 4dbd595e4..8e7402ddd 100644 --- a/README.md +++ b/README.md @@ -197,21 +197,28 @@ include declarations with a lower access level, set the `--min-acl` flag to `int In Objective-C mode, Jazzy documents all declarations found in the `--umbrella-header` header file and any other header files included by it. -You can then prevent some of these declarations from being documented using `--exclude` -or `:nodoc:`. - -The `--exclude` flag lists source files to omit from the documentation. Entries in the -list can be absolute pathnames beginning with `/` or relative pathnames. Relative -pathnames are interpreted relative to the directory from where you run `jazzy` or, if the -exclude flag is set in the config file, relative to the directory containing the config -file. Entries in the list can match multiple files using `*` to match any number of -characters including `/`. For example: -* `jazzy --exclude=/Users/fred/project/Sources/Secret.swift` -- exclude a specific file +You can control exactly which declarations should be documented using `--exclude`, +`--include`, or `:nodoc:`. + +The `--include` and `--exclude` flags list source files that should be included/excluded +respectively in the documentation. Entries in the list can be absolute pathnames beginning +with `/` or relative pathnames. Relative pathnames are interpreted relative to the +directory from where you run `jazzy` or, if the flags are set in the config file, relative +to the directory containing the config file. Entries in the list can match multiple files +using `*` to match any number of characters including `/`. For example: +* `jazzy --include=/Users/fred/project/Sources/Secret.swift` -- include a specific file * `jazzy --exclude=/*/Internal*` -- exclude all files with names that begin with *Internal* and any files under any directory with a name beginning *Internal*. * `jazzy --exclude=Impl1/*,Impl2/*` -- exclude all files under the directories *Impl1* and *Impl2* found in the current directory. +Note that the `--include` option is applied before the `--exclude` option. For example: + +* `jazzy --include=/*/Internal* --exclude=Impl1/*,Impl2/*` -- include all files with names + that begin with *Internal* and any files under any directory with a name beginning + *Internal*, **except** for those under the directories *Impl1* and *Impl2* found in the + current directory + Declarations with a documentation comment containing `:nodoc:` are excluded from the documentation. diff --git a/lib/jazzy/config.rb b/lib/jazzy/config.rb index 4d42989a3..312e6573f 100644 --- a/lib/jazzy/config.rb +++ b/lib/jazzy/config.rb @@ -167,6 +167,15 @@ def expand_path(path) Array(files).map { |f| expand_path(f).to_s } end + config_attr :included_files, + command_line: ['-i', '--include filepath1,filepath2,…filepathN', Array], + description: 'Source file pathnames to be included in documentation. '\ + 'Supports wildcards.', + default: [], + parse: ->(files) do + Array(files).map { |f| expand_path(f).to_s } + end + config_attr :swift_version, command_line: '--swift-version VERSION', default: nil, diff --git a/lib/jazzy/sourcekitten.rb b/lib/jazzy/sourcekitten.rb index 9ea06d975..5dc5fec1f 100644 --- a/lib/jazzy/sourcekitten.rb +++ b/lib/jazzy/sourcekitten.rb @@ -538,11 +538,33 @@ def self.mark_members_from_protocol_extension(extensions) end end + # Apply filtering based on the "included" and "excluded" flags. + def self.filter_files(json) + json = filter_included_files(json) if Config.instance.included_files.any? + json = filter_excluded_files(json) if Config.instance.excluded_files.any? + json.map do |doc| + key = doc.keys.first + doc[key] + end.compact + end + + # Filter based on the "included" flag. + def self.filter_included_files(json) + included_files = Config.instance.included_files + json.map do |doc| + key = doc.keys.first + doc if included_files.detect do |include| + File.fnmatch?(include, key) + end + end.compact + end + + # Filter based on the "excluded" flag. def self.filter_excluded_files(json) excluded_files = Config.instance.excluded_files json.map do |doc| key = doc.keys.first - doc[key] unless excluded_files.detect do |exclude| + doc unless excluded_files.detect do |exclude| File.fnmatch?(exclude, key) end end.compact @@ -665,7 +687,7 @@ def self.parse(sourcekitten_output, min_acl, skip_undocumented, inject_docs) @min_acl = min_acl @skip_undocumented = skip_undocumented @stats = Stats.new - sourcekitten_json = filter_excluded_files(JSON.parse(sourcekitten_output)) + sourcekitten_json = filter_files(JSON.parse(sourcekitten_output)) docs = make_source_declarations(sourcekitten_json).concat inject_docs docs = expand_extensions(docs) docs = deduplicate_declarations(docs)