Improve file enumeration in generate subcommand (#229)

* Include isDirectory key in file enumerator

Skip hidden files and package descendents during file enumeration

* Skip top-level Tests directory

* Update end-to-end tests to pass current directory as argument

* Add changelog entry for #229

* Use skipDescendants, which is available on Linux.

* Document new directory enumeration behavior in README

Co-authored-by: Lukas Stührk <[email protected]>

Author: mattt

Changelog.md

@@ -25,6 +25,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Changed display of code declarations in HTML.
   #204 by @mattt.
+- Changed the `generate` command to skip hidden files
+  and top-level `Tests` directories.
+  #229 by @mattt.
 
 ## [1.0.0-beta.5] - 2020-09-29
 

README.md

@@ -107,13 +107,16 @@ $ apt-get install -y libxml2-dev graphviz
                               be included. (default: public)
       -h, --help              Show help information.
 
-The `generate` subcommand 
+The `generate` subcommand
 takes one or more paths and enumerates them recursively,
 collecting all Swift files into a single "module"
 and generating documentation accordingly.
+Any hidden directories are skipped,
+including `.git` and other directories with paths starting with a dot (`.`).
+Top-level `Tests` directories are skipped as well.
 
 ```terminal
-$ swift doc generate path/to/SwiftProject/Sources --module-name SwiftProject
+$ swift doc generate path/to/SwiftProject --module-name SwiftProject
 $ tree .build/documentation
 $ documentation/
 ├── Home

Sources/SwiftDoc/Module.swift

@@ -22,15 +22,27 @@ public final class Module {
         let fileManager = FileManager.default
         for path in paths {
             let directory = URL(fileURLWithPath: path)
-            guard let directoryEnumerator = fileManager.enumerator(at: directory, includingPropertiesForKeys: nil) else { continue }
+            guard let directoryEnumerator = fileManager.enumerator(at: directory, includingPropertiesForKeys: [.isDirectoryKey], options: [.skipsHiddenFiles, .skipsPackageDescendants]) else { continue }
             for case let url as URL in directoryEnumerator {
                 var isDirectory: ObjCBool = false
                 guard url.pathExtension == "swift",
                     fileManager.isReadableFile(atPath: url.path),
-                    fileManager.fileExists(atPath: url.path, isDirectory: &isDirectory),
-                    isDirectory.boolValue == false
-                else { continue }
-                sources.append((url, directory))
+                    fileManager.fileExists(atPath: url.path, isDirectory: &isDirectory)
+                else {
+                    // Skip top-level Tests directory
+                    if isDirectory.boolValue == true,
+                       url.lastPathComponent == "Tests",
+                       directory.appendingPathComponent("Tests").path == url.path
+                    {
+                        directoryEnumerator.skipDescendants()
+                    }
+
+                    continue
+                }
+
+                if isDirectory.boolValue == false {
+                    sources.append((url, directory))
+                }
             }
         }
 

Tests/EndToEndTests/GenerateSubcommandTests.swift

@@ -13,7 +13,7 @@ final class GenerateSubcommandTests: XCTestCase {
                             "--module-name", "SwiftDoc",
                             "--format", "commonmark",
                             "--output", outputDirectory.path,
-                            "Sources"
+                            "."
                         ]
         ) { result in
             XCTAssertEqual(result.terminationStatus, EXIT_SUCCESS)
@@ -54,7 +54,7 @@ final class GenerateSubcommandTests: XCTestCase {
                             "--module-name", "SwiftDoc",
                             "--format", "html",
                             "--output", outputDirectory.path,
-                            "Sources"
+                            "."
                         ]
         ) { result in
             XCTAssertEqual(result.terminationStatus, EXIT_SUCCESS)