🔀 Merge pull request #31 from davep/docs

Add documentation

Author: davep

.gitignore

@@ -6,3 +6,5 @@
 build/
 dist/
 __pycache__
+site/
+.screenshot_cache/

.images/file-open.png

@@ -1,11 +1,13 @@
-lib    := textual_fspicker
-src    := src/
-run    := rye run
-test   := rye test
-python := $(run) python
-lint   := rye lint -- --select I
-fmt    := rye fmt
-mypy   := $(run) mypy
+lib      := textual_fspicker
+src      := src/
+examples := docs/examples
+run      := rye run
+test     := rye test
+python   := $(run) python
+lint     := rye lint -- --select I
+fmt      := rye fmt
+mypy     := $(run) mypy
+mkdocs   := $(run) mkdocs
 
 ##############################################################################
 # Local "interactive testing" of the code.
@@ -40,23 +42,37 @@ resetup: realclean		# Recreate the virtual environment from scratch
 # Checking/testing/linting/etc.
 .PHONY: lint
 lint:				# Check the code for linting issues
-	$(lint) $(src)
+	$(lint) $(src) $(examples)
 
 .PHONY: codestyle
 codestyle:			# Is the code formatted correctly?
-	$(fmt) --check $(src)
+	$(fmt) --check $(src) $(examples)
 
 .PHONY: typecheck
 typecheck:			# Perform static type checks with mypy
-	$(mypy) --scripts-are-modules $(src)
+	$(mypy) --scripts-are-modules $(src) $(examples)
 
 .PHONY: stricttypecheck
 stricttypecheck:	        # Perform a strict static type checks with mypy
-	$(mypy) --scripts-are-modules --strict $(src)
+	$(mypy) --scripts-are-modules --strict $(src) $(examples)
 
 .PHONY: checkall
 checkall: codestyle lint stricttypecheck # Check all the things
 
+##############################################################################
+# Documentation.
+.PHONY: docs
+docs:                           # Generate the system documentation
+	$(mkdocs) build
+
+.PHONY: rtfm
+rtfm:                           # Locally read the library documentation
+	$(mkdocs) serve
+
+.PHONY: publishdocs
+publishdocs: docs		# Set up the docs for publishing
+	$(run) ghp-import --push site
+
 ##############################################################################
 # Package/publish.
 .PHONY: package
@@ -83,11 +99,11 @@ repl:				# Start a Python REPL in the venv.
 
 .PHONY: delint
 delint:			# Fix linting issues.
-	$(lint) --fix  $(src)
+	$(lint) --fix $(src) $(examples)
 
 .PHONY: pep8ify
 pep8ify:			# Reformat the code to be as PEP8 as possible.
-	$(fmt) $(src)
+	$(fmt) $(src) $(examples)
 
 .PHONY: tidy
 tidy: delint pep8ify		# Tidy up the code, fixing lint and format issues.

.images/file-save.png

@@ -1,14 +1,13 @@
 # textual-fspicker
 
-![Viewing its own directory](https://raw.githubusercontent.com/davep/textual-fspicker/main/img/textual-fspicker.png)
-*An example of `textual-fspicker` being used in a Textual application*
-
 ## Introduction
 
 This library provides a simple set of filesystem navigation and picking
-dialogs (actually, as of the time of writing, it only provides two, this is
-a very early WiP you're seeing). The aim is to provide "ready to go" dialogs
-that should also be fairly easy to tailor to your own applications.
+dialogs The aim is to provide "ready to go" dialogs that should also be
+fairly easy to tailor to your own applications.
+
+![Opening a file](https://raw.githubusercontent.com/davep/textual-fspicker/main/.images/file-open.png)
+![Saving a file](https://raw.githubusercontent.com/davep/textual-fspicker/main/.images/file-save.png)
 
 ## Installing
 
@@ -18,33 +17,17 @@ The package can be installed with `pip` or related tools, for example:
 $ pip install textual-fspicker
 ```
 
-## The library
-
-Right at the moment there's just two dialogs available:
+## Using the library
 
-- `FileOpen` -- For selecting a file from the filesystem.
-- `FileSave` -- For selecting a file for saving in the filesystem.
-- `SelectDirectory` -- For selecting a directory from the filesysrem.
-
-You can see them in action in the [demo/test
-code](https://github.com/davep/textual-fspicker/blob/main/src/textual_fspicker/__main__.py).
-
-Yes, I know that documentation is lacking right now -- I'm still fleshing
-out how this will work and what it will provide -- so the best place to see
-how the code can be used is in that demo/test code.
+Please see [the main documentation for the
+library](https://blog.davep.org/textual-fspicker/) for details on how to use
+it.
 
 ## TODO
 
-- [ ] Flesh out what's displayed for directory entries
-- [ ] Add lots of styling options for directory entries
-- [ ] Settle on a final set of default styles for the dialogs
-- [X] Add a more file-save-oriented dialog
-- [X] Add a directory picking dialog
-- [X] Add file filtering (extensions using `Select`)
-- [X] Expose the hidden show/hide facility of the navigator in the dialogs
-- [ ] Better documentation
-- [X] Test on Windows
-- [ ] Add custom mtime formatting
-- [ ] Add support for showing different times
+See [the TODO tag in
+issues](https://github.com/davep/textual-fspicker/issues?q=is%3Aissue+is%3Aopen+label%3ATODO)
+to see what I'm planning.
+
 
 [//]: # (README.md ends here)

Makefile

@@ -0,0 +1,21 @@
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.widgets import Button, Label
+
+from textual_fspicker import FileOpen
+
+
+class DefaultFileOpenApp(App[None]):
+    def compose(self) -> ComposeResult:
+        yield Button("Press to open a file")
+        yield Label()
+
+    @on(Button.Pressed)
+    @work
+    async def open_a_file(self) -> None:
+        if opened := await self.push_screen_wait(FileOpen(must_exist=False)):
+            self.query_one(Label).update(str(opened))
+
+
+if __name__ == "__main__":
+    DefaultFileOpenApp().run()

README.md

@@ -0,0 +1,21 @@
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.widgets import Button, Label
+
+from textual_fspicker import FileOpen
+
+
+class BasicFileOpenApp(App[None]):
+    def compose(self) -> ComposeResult:
+        yield Button("Press to open a file")
+        yield Label()
+
+    @on(Button.Pressed)
+    @work
+    async def open_a_file(self) -> None:
+        if opened := await self.push_screen_wait(FileOpen()):
+            self.query_one(Label).update(str(opened))
+
+
+if __name__ == "__main__":
+    BasicFileOpenApp().run()

docs/examples/guide/any_open_file.py

@@ -0,0 +1,21 @@
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.widgets import Button, Label
+
+from textual_fspicker import FileSave
+
+
+class BasicFileSaveApp(App[None]):
+    def compose(self) -> ComposeResult:
+        yield Button("Press to save a file")
+        yield Label()
+
+    @on(Button.Pressed)
+    @work
+    async def save_a_file(self) -> None:
+        if opened := await self.push_screen_wait(FileSave()):
+            self.query_one(Label).update(str(opened))
+
+
+if __name__ == "__main__":
+    BasicFileSaveApp().run()

docs/examples/guide/basic_open_file.py

@@ -0,0 +1,21 @@
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.widgets import Button, Label
+
+from textual_fspicker import SelectDirectory
+
+
+class BasicSelectDirectoryApp(App[None]):
+    def compose(self) -> ComposeResult:
+        yield Button("Press to select a directory")
+        yield Label()
+
+    @on(Button.Pressed)
+    @work
+    async def pick_a_directory(self) -> None:
+        if opened := await self.push_screen_wait(SelectDirectory()):
+            self.query_one(Label).update(str(opened))
+
+
+if __name__ == "__main__":
+    BasicSelectDirectoryApp().run()

docs/examples/guide/basic_save_file.py

@@ -0,0 +1,21 @@
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.widgets import Button, Label
+
+from textual_fspicker import FileOpen
+
+
+class DefaultFileOpenApp(App[None]):
+    def compose(self) -> ComposeResult:
+        yield Button("Press to open a file")
+        yield Label()
+
+    @on(Button.Pressed)
+    @work
+    async def open_a_file(self) -> None:
+        if opened := await self.push_screen_wait(FileOpen(default_file="README.md")):
+            self.query_one(Label).update(str(opened))
+
+
+if __name__ == "__main__":
+    DefaultFileOpenApp().run()

docs/examples/guide/basic_select_directory.py

@@ -0,0 +1,21 @@
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.widgets import Button, Label
+
+from textual_fspicker import FileSave
+
+
+class DefaultSaveFileApp(App[None]):
+    def compose(self) -> ComposeResult:
+        yield Button("Press to save a file")
+        yield Label()
+
+    @on(Button.Pressed)
+    @work
+    async def save_a_file(self) -> None:
+        if opened := await self.push_screen_wait(FileSave(default_file="example.md")):
+            self.query_one(Label).update(str(opened))
+
+
+if __name__ == "__main__":
+    DefaultSaveFileApp().run()

docs/examples/guide/default_open_file.py

@@ -0,0 +1,32 @@
+from textual import work
+from textual.app import App
+from textual.widgets import Label
+
+from textual_fspicker import FileOpen, Filters
+
+
+class BasicFileOpenApp(App[None]):
+    CSS = """
+    FileOpen Dialog {
+        height: 50%;
+    }
+    """
+
+    @work
+    async def on_mount(self) -> None:
+        if opened := await self.push_screen_wait(
+            FileOpen(
+                filters=Filters(
+                    ("Python", lambda p: p.suffix.lower() == ".py"),
+                    ("Markdown", lambda p: p.suffix.lower() == ".md"),
+                    ("TOML", lambda p: p.suffix.lower() == ".toml"),
+                    ("YAML", lambda p: p.suffix.lower() == ".yml"),
+                    ("All", lambda _: True),
+                )
+            )
+        ):
+            self.query_one(Label).update(str(opened))
+
+
+if __name__ == "__main__":
+    BasicFileOpenApp().run()

docs/examples/guide/default_save_file.py

@@ -0,0 +1,21 @@
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.widgets import Button, Label
+
+from textual_fspicker import FileSave
+
+
+class DefaultSaveFileApp(App[None]):
+    def compose(self) -> ComposeResult:
+        yield Button("Press to save a file")
+        yield Label()
+
+    @on(Button.Pressed)
+    @work
+    async def save_a_file(self) -> None:
+        if opened := await self.push_screen_wait(FileSave(can_overwrite=False)):
+            self.query_one(Label).update(str(opened))
+
+
+if __name__ == "__main__":
+    DefaultSaveFileApp().run()

docs/examples/guide/filter_open.py

@@ -0,0 +1,14 @@
+from textual import work
+from textual.app import App
+
+from textual_fspicker import FileOpen
+
+
+class OpenAFileApp(App[None]):
+    @work
+    async def on_mount(self) -> None:
+        await self.push_screen_wait(FileOpen())
+
+
+if __name__ == "__main__":
+    OpenAFileApp().run()

docs/examples/guide/no_overwrite_save_file.py

@@ -0,0 +1,14 @@
+from textual import work
+from textual.app import App
+
+from textual_fspicker import FileSave
+
+
+class SaveAFileApp(App[None]):
+    @work
+    async def on_mount(self) -> None:
+        await self.push_screen_wait(FileSave())
+
+
+if __name__ == "__main__":
+    SaveAFileApp().run()

docs/examples/index/open_a_file.py

@@ -0,0 +1,14 @@
+from textual import work
+from textual.app import App
+
+from textual_fspicker import SelectDirectory
+
+
+class SelectADirectoryApp(App[None]):
+    @work
+    async def on_mount(self) -> None:
+        await self.push_screen_wait(SelectDirectory())
+
+
+if __name__ == "__main__":
+    SelectADirectoryApp().run()