Preliminary docs; add base notes support

.pre-commit-config.yaml

@@ -25,6 +25,16 @@ repos:
     hooks:
       - id: poetry-check
       - id: poetry-lock
+  - repo: https://github.com/tcort/markdown-link-check
+    rev: v3.11.2
+    hooks:
+      - id: markdown-link-check
+        args: ["--config", "tests/config/mlc_config.json"]
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.35.0
+    hooks:
+      - id: markdownlint
+        args: ["--config", "tests/config/markdownlint.json"]
   - repo: local
     hooks:
       - id: pytest

CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at [email protected]. All
+reported by contacting the project team at <[email protected]>. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.
@@ -67,10 +67,8 @@ members of the project's leadership.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
-
-[homepage]: https://www.contributor-covenant.org
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 1.4,
+available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
 
 For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+<https://www.contributor-covenant.org/faq>

README.md

@@ -1,96 +1,40 @@
 # Task (cade-task)
 
-Task is a light CLI wrapper around Reminders.app ([reminders-cli](https://github.com/keith/reminders-cli)) that unifies use with dead-simple, sane defaults to remove friction from GTD.
+Task is a light CLI wrapper around Reminders.app ([reminders-cli](https://github.com/keith/reminders-cli)) with sane defaults to remove friction from GTD.
 
-## Install
+## Quick Start
+
+### Install
 
 [pipx](https://pypa.github.io/pipx/):
 
-```
+```sh
 pipx install cade-task
 ```
 
-[brew](https://brew.sh/):
-
-*Building bottles of python modules is flaky, not currently maintained*
-
-```
-brew install cadeef/tap/cade-task
-```
-
-## Usage
-
-Commands are aware of project context where available. Task assumes you store all of your projects in the same directory (defined with `—-project-dir`), shell aliases are your friend.
-
-Short flags exist for all options, but the long version is used here for clarity.
-
-### List Tasks
-
-List tasks for your current project:
-
-```
-task list
-```
-
-Not in your project directory? No problem, specify the list you’d like to interact with:
-
-```
-task list —-list <yourgloriouslist>
-```
-
-The list selection convention is consistent throughout the app.
-
-### Add a Task
+More [install options](https://task.cade.pro/install.html) availble.
 
-```
-task add A glorious task that should be completed
-```
+### Set your project directory
 
-Don’t worry about quotes unless you’re doing something funky, task will glue the arguments together for you.
-
-### Complete Tasks
-
-Complete one or more tasks:
+Export `TASK_PROJECT_DIR` for your shell environment:
 
+```sh
+export TASK_PROJECT_DIR="${HOME}/awesome_stuff"
 ```
-task complete 6 1 3
-```
-
-Tasks are completed in reverse numerical order (10...1) to avoid re-parsing the task list after each task is completed.
-
-### Open Reminders.app
-
-Conveniently open (or bring to the foreground) Reminders.app:
-
-```
-task open
-```
-
-______________________________________________________________________
-
-Additional usage information is available via `—-help` on the command line.
-
-### Shell Aliases
 
-The defaults may not work for you. Shell aliases are cheap and easy. Define a different project directory from bash:
+### Go
 
-```bash
-TASK_PROJECT_DIR=“${HOME}/myprettyneatprojectdir”
-# List tasks in current project
-alias t=“task -d ${TASK_PROJECT_DIR} list”
-# Add task in current project
-alias ta=“task -d ${TASK_PROJECT_DIR} add”
-# Complete task(s) in current project
-alias tc=“task -d ${TASK_PROJECT_DIR} complete”
-# Sync TODO|FIXME in current project
-alias tsync=“task -d ${TASK_PROJECT_DIR} sync”
-# List task lists
-alias tl=“task lists”
-# Open Reminders.app
-alias to=“task open”
+```sh
+$ task list
+               Tasks
+┌───┬─────────────────────────────┐
+│ 0 │ Refactor code, all of it    │
+│ 1 │ Add testing to generator    │
+│ 2 │ Push to prod Friday evening │
+└───┴─────────────────────────────┘
 ```
 
-Tweak until your heart is content without monkeying yet another config file.
+Check out [usage](https://task.cade.pro/usage.html) or `--help` for more commands.
 
 ## Caveats
 

cade_task/cli.py

@@ -102,8 +102,7 @@ def add(
     Add a task to a given project
     """
     project = project_set(project, ctx.obj["project"])
-    title_str = " ".join(title)
-    task = TaskItem(title_str, project)
+    task = TaskItem(title, project)
     new_task = task.add()
     print(f":white_check_mark: Task '{new_task.title}' added to {new_task.parent}.")
 
@@ -116,11 +115,10 @@ def edit(
     project: Annotated[Optional[str], typer.Option("--list")] = None,
 ) -> None:
     """
-    Add a task to a given project
+    Edit a task
     """
     project = project_set(project, ctx.obj["project"])
-    title_str = " ".join(title)
-    task = TaskItem(title_str, project, index=index)
+    task = TaskItem(title, project, index=index)
     task.edit()
     print(
         f":white_check_mark: Task {index} modified to '{task.title}' in {task.parent}."

cade_task/lib.py

@@ -8,22 +8,36 @@
 # from devtools import debug  # noqa: F401
 
 
-@dataclass
 class TaskItem(object):
     """Reminder/task"""
 
-    title: str
-    parent: str
-    id: str | None = None
-    is_complete: bool | None = None
-    priority: int | None = None
-    index: int | None = None
+    def __init__(
+        self,
+        title: str | list,
+        parent: str,
+        task_id: str | None = None,
+        is_complete: bool | None = None,
+        priority: int | None = None,
+        index: int | None = None,
+        notes: str | None = None,
+    ) -> None:
+        if isinstance(title, list):
+            self.title = " ".join(title)
+        else:
+            self.title = title
+
+        self.parent = parent
+        self.task_id = task_id
+        self.is_complete = is_complete
+        self.priority = priority
+        self.index = index
+        self.notes = notes
 
     @staticmethod
     def from_dict(task: dict[str, Any]) -> "TaskItem":
         # Clean up naming convention
         rename_rules = {
-            "externalId": "id",
+            "externalId": "task_id",
             "isCompleted": "is_complete",
             "list": "parent",
         }
@@ -40,7 +54,7 @@ def add(self) -> "TaskItem":
         return task
 
     def complete(self):
-        run_and_return(["complete", self.parent, str(self.index)])
+        run_and_return(["complete", self.parent, self.index])
 
     def edit(self):
         run_and_return(["edit", self.parent, self.index, self.title], mode="raw")
@@ -121,8 +135,13 @@ class RunAndReturnResult:
 
 
 def run_and_return(
-    cmd: list[str], mode: str = "raw", inject_reminder: bool = True
+    cmd: list[str | Path | int], mode: str = "raw", inject_reminder: bool = True
 ) -> RunAndReturnResult:
+    # Cast ints as str
+    for i, v in enumerate(cmd.copy()):
+        if isinstance(v, int):
+            cmd[i] = str(v)
+
     # Add reminders path to beginning of command
     if inject_reminder:
         cmd = [reminders()] + cmd
@@ -131,7 +150,7 @@ def run_and_return(
         cmd = cmd + ["--format", "json"]
 
     try:
-        result = run(cmd, capture_output=True, check=True, shell=False)
+        result = run(cmd, capture_output=True, check=True, shell=False)  # type: ignore[arg-type]  # noqa: E501
     except CalledProcessError as e:
         raise TaskCommandException(e)
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,48 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "cade-task"
+copyright = "2023, Cade Ekblad-Frank"
+author = "Cade Ekblad-Frank"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "myst_parser",
+    "sphinx_copybutton",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "press"
+html_static_path = ["_static"]
+
+# -- MyST configuration
+myst_enable_extensions = [
+    # "amsmath",
+    # "attrs_inline",
+    "colon_fence",
+    # "deflist",
+    # "dollarmath",
+    # "fieldlist",
+    # "html_admonition",
+    # "html_image",
+    # "linkify",
+    # "replacements",
+    "smartquotes",
+    # "strikethrough",
+    # "substitution",
+    # "tasklist",
+]

docs/index.md

@@ -0,0 +1,10 @@
+# Task
+
+:::{toctree}
+:hidden:
+install.md
+usage.md
+:::
+
+:::{include} ../README.md
+:::

docs/install.md

@@ -0,0 +1,15 @@
+# Install
+
+[pipx](https://pypa.github.io/pipx/):
+
+```sh
+pipx install cade-task
+```
+
+[brew](https://brew.sh/):
+
+Building bottles of python modules is flaky, **not currently maintained**
+
+```sh
+brew install cadeef/tap/cade-task
+```