Document the filtering support of DirectoryTree

docs/examples/widgets/directory_tree_filtered.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+from typing import Iterable
+
+from textual.app import App, ComposeResult
+from textual.widgets import DirectoryTree
+
+
+class FilteredDirectoryTree(DirectoryTree):
+    def filter_paths(self, paths: Iterable[Path]) -> Iterable[Path]:
+        return [path for path in paths if not path.name.startswith(".")]
+
+
+class DirectoryTreeApp(App):
+    def compose(self) -> ComposeResult:
+        yield FilteredDirectoryTree("./")
+
+
+if __name__ == "__main__":
+    app = DirectoryTreeApp()
+    app.run()

docs/widgets/directory_tree.md

@@ -14,6 +14,26 @@ The example below creates a simple tree to navigate the current working director
 --8<-- "docs/examples/widgets/directory_tree.py"
 ```
 
+## Filtering
+
+There may be times where you want to filter what appears in the
+`DirectoryTree`. To do this inherit from `DirectoryTree` and implement your
+own version of the `filter_paths` method. It should take an iterable of
+Python `Path` objects, and return those that pass the filter. For example,
+if you wanted to take the above code an filter out all of the "hidden" files
+and directories:
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/directory_tree_filtered.py"}
+    ```
+
+=== "directory_tree_filtered.py"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/directory_tree_filtered.py"
+    ~~~
+
 ## Messages
 
 ### ::: textual.widgets.DirectoryTree.FileSelected

src/textual/widgets/_directory_tree.py

@@ -157,6 +157,10 @@ class DirectoryTree(Tree[DirEntry]):
 
         Returns:
             The filtered paths.
+
+        By default this method returns all of the paths provided. To create
+        a filtered `DirectoryTree` inherit from it and implement your own
+        version of this method.
         """
         return paths