Merge e3cbe61 into e5ae99d

lyz-code · Aug 13, 2021 · ba3b9fb · ba3b9fb
2 parents e5ae99d + e3cbe61
commit ba3b9fb
Show file tree

Hide file tree

Showing 29 changed files with 759 additions and 99 deletions.
diff --git a/Makefile b/Makefile
@@ -1,6 +1,6 @@
 .DEFAULT_GOAL := test
-isort = isort src docs/examples tests setup.py
-black = black --target-version py37 src docs/examples tests setup.py
+isort = isort src tests setup.py
+black = black --target-version py37 src tests setup.py
 
 .PHONY: install
 install:
@@ -67,7 +67,7 @@ mypy:
 	@echo ""
 
 .PHONY: test
-test: test-code test-examples
+test: test-code
 
 .PHONY: test-code
 test-code:
@@ -123,7 +123,7 @@ clean:
 	@echo ""
 
 .PHONY: docs
-docs: test-examples
+docs:
 	@echo "-------------------------"
 	@echo "- Serving documentation -"
 	@echo "-------------------------"
@@ -158,7 +158,7 @@ build-package: clean
 	@echo ""
 
 .PHONY: build-docs
-build-docs: test-examples
+build-docs:
 	@echo "--------------------------"
 	@echo "- Building documentation -"
 	@echo "--------------------------"

diff --git a/docs/adr/001-high_level_problem_analysis.md b/docs/adr/001-high_level_problem_analysis.md
@@ -3,7 +3,7 @@ Date: 2021-07-12
 # Status
 <!-- What is the status? Draft, Proposed, Accepted, Rejected, Deprecated or Superseded?
 -->
-Draft
+Accepted
 
 # Context
 <!-- What is the issue that we're seeing that is motivating this decision or change? -->

diff --git a/docs/adr/002-initial_program_design.md b/docs/adr/002-initial_program_design.md
@@ -3,7 +3,7 @@ Date: 2021-07-12
 # Status
 <!-- What is the status? Draft, Proposed, Accepted, Rejected, Deprecated or Superseded?
 -->
-Draft
+Accepted
 
 # Context
 <!-- What is the issue that we're seeing that is motivating this decision or change? -->
@@ -86,8 +86,7 @@ processing sessions. Postponing it will make the item show at the next session.
 The element prioritization is done by:
 
 * Element category type: Each category will have a priority.
-* Element creation date: The user will choose the order to address first the
-    oldest or the newest elements.
+* Element creation date: Ordered by oldest first.
 
 It will measure the time spent between each element, and if it surpasses
 a defined amount, it will warn the user, so it is aware of it and can act

diff --git a/docs/adr/003-markup_definition.md b/docs/adr/003-markup_definition.md
@@ -15,7 +15,6 @@ The information to extract from each element is:
 * Description.
 * Body
 * Element type.
-* Priority.
 
 # Proposals
 <!-- What are the possible solutions to the problem described in the context -->

diff --git a/docs/adr/adr.md b/docs/adr/adr.md
@@ -15,9 +15,9 @@ graph TD
     click 002 "https://lyz-code.github.io/pynbox/adr/002-initial_program_design" _blank
     click 002 "https://lyz-code.github.io/pynbox/adr/003-markup_definition" _blank
 
-    001:::draft
-    002:::draft
-    003:::draft
+    001:::accepted
+    002:::accepted
+    003:::accepted
 
     classDef draft fill:#CDBFEA;
     classDef proposed fill:#B1CCE8;

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,39 @@
+The first time you use `pynbox`, it will create the default configuration in
+`~/.local/share/pynbox` or the path of the `-c` command line argument.
+
+# database_url
+
+`pynbox` uses [`repository_orm`](https://lyz-code.github.io/repository-orm/) to
+persist the elements. By default, it uses the
+[TinyDB](https://tinydb.readthedocs.io/en/latest/usage.html) backend, if you
+encounter performance issues, move to
+[SQLite](https://lyz-code.github.io/repository-orm/pypika_repository/), and then
+to MySQL. Refer to the docs of
+[`repository_orm`](https://lyz-code.github.io/repository-orm/) to do so.
+
+# max_time
+
+You should not spend too much time processing your inbox, the idea is that if it
+will take you more than 2 minutes to process an element, it's better to create
+a task to address it. `max_time` defines the maximum number of seconds to
+process an element. A warning will be shown if it takes you longer.
+
+# types
+
+It's where you define the element categories, their regular expressions and
+their priority. For example:
+
+```yaml
+types:
+  task:
+    regexp: t\.
+    priority: 4
+  idea:
+    regexp: i\.
+```
+
+If the priority is not defined, it's assumed to be `3`.
+
+!!! note "The regular expression needs to be a non capturing one"
+    If you use parenthesis use `(?:<regular expression>)` instead of `(<regular
+    expression>)`.
diff --git a/docs/creating_new_elements.md b/docs/creating_new_elements.md
@@ -0,0 +1,52 @@
+
+To add new elements into pynbox, you need to use the defined [markup
+language](#pynbox-markup-language) either through the [command
+line](#command-line) or through a [file](#parse-file).
+
+# Pynbox markup language
+
+It's designed to use the minimum number of friendly keystrokes both for a mobile
+and a laptop. The format of each element is:
+
+```
+{{ type_identifier }} {{ description }}
+{{ body }}
+```
+
+Where:
+
+* `type_identifier`: Is a case insensitive string of the fewest letters as
+    possible, that identifies the type of the element. It can be for example
+    `t.` for a task, or `i.` for an idea. The identifiers are defined in the
+    [configuration file](configuration.md).
+* `description`: A short sentence that defines the element.
+* `body`: An optional group of paragraphs with more information of the element.
+
+For example:
+
+```
+T. buy groceries
+* milk
+* tofu
+i. to have an inbox management tool would be awesome!
+```
+
+# Command line
+
+You can use the `add` subcommand to put new items into the inbox.
+
+```bash
+pynbox add t. buy milk
+```
+
+# Parse a file
+
+If you need to add elements with a body, more than one element, or want to
+import them from other device, using a file might be easier.
+
+Write the elements one after the other in the file and then use the `parse`
+command.
+
+```bash
+pynbox parse file.txt
+```
diff --git a/docs/examples/simple-example.py b/docs/examples/simple-example.py
diff --git a/docs/img/screencast.gif b/docs/img/screencast.gif
diff --git a/docs/index.md b/docs/index.md
@@ -2,19 +2,35 @@
 [![Actions Status](https://github.com/lyz-code/pynbox/workflows/Build/badge.svg)](https://github.com/lyz-code/pynbox/actions)
 [![Coverage Status](https://coveralls.io/repos/github/lyz-code/pynbox/badge.svg?branch=master)](https://coveralls.io/github/lyz-code/pynbox?branch=master)
 
-Task management inbox tool
+`pynbox` aims to help you with the daily [emptying of the
+inbox](https://lyz-code.github.io/blue-book/task_tools/#inbox) by:
+
+* Prioritizing the elements by their type.
+* Giving insights on the inbox status.
+* Giving feedback on the inbox processing process.
+* Making the insertion of new elements as effortless as possible.
 
 # Installing
 
 ```bash
 pip install pynbox
 ```
 
-# A Simple Example
+# Quick overview
 
-```python
-{! examples/simple-example.py !} # noqa
-```
+![ ](screencast.gif)
+
+# Proposed workflow
+
+When you're on your desktop you can add elements directly with the [command
+line](creating_new_elements.md#command-line), when you're on the go, use any
+text editor, such as
+[Markor](https://f-droid.org/en/packages/net.gsantner.markor/), and sync the
+file with [Syncthing](https://lyz-code.github.io/blue-book/linux/syncthing/) to
+your laptop, and then [parse the file](creating_new_elements.md#parse-a-file).
+
+To process the elements, you can daily use `pynbox process`. If you want to
+focus on a category, use `pynbox process category`.
 
 # References
 

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -28,7 +28,7 @@ htmlmin==0.1.12
     # via mkdocs-minify-plugin
 idna==3.2
     # via requests
-importlib-metadata==4.6.3
+importlib-metadata==4.6.4
     # via
     #   click
     #   markdown

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -4,12 +4,16 @@ site_author: Lyz
 site_url: https://lyz-code.github.io/pynbox
 nav:
   - pynbox: index.md
+  - Creating new elements: creating_new_elements.md
+  - Configuration: configuration.md
   - Reference: reference.md
   - Contributing: contributing.md
   - Architecture Decision Records:
       - adr/adr.md
       - '001: High level problem analysis': |
           adr/001-high_level_problem_analysis.md
+      - '002: Initial program design': adr/002-initial_program_design.md
+      - '003: Markup Definition': adr/003-markup_definition.md
 
 plugins:
   - search

diff --git a/mypy.ini b/mypy.ini
@@ -25,3 +25,9 @@ ignore_missing_imports = True
 
 [mypy-pytest.*]
 ignore_missing_imports = True
+
+[mypy-pkg_resources.*]
+ignore_missing_imports = True
+
+[mypy-pexpect.*]
+ignore_missing_imports = True
diff --git a/requirements-dev.in b/requirements-dev.in
@@ -7,6 +7,7 @@ pytest-cov
 pytest-pythonpath
 pytest-xdist
 pytest-freezegun
+pexpect
 
 # Linting
 yamllint

diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -66,7 +66,14 @@ click==8.0.1
     #   safety
     #   yamlfix
 colorama==0.4.4
-    # via flakehell
+    # via
+    #   -r requirements.txt
+    #   flakehell
+    #   rich
+commonmark==0.9.1
+    # via
+    #   -r requirements.txt
+    #   rich
 coverage==5.5
     # via pytest-cov
 deepdiff==5.5.0
@@ -116,7 +123,7 @@ flake8-annotations-complexity==0.0.6
     # via -r requirements-dev.in
 flake8-bugbear==21.4.3
     # via -r requirements-dev.in
-flake8-comprehensions==3.5.0
+flake8-comprehensions==3.6.0
     # via -r requirements-dev.in
 flake8-debugger==4.0.0
     # via -r requirements-dev.in
@@ -175,7 +182,7 @@ idna==3.2
     # via
     #   -r docs/requirements.txt
     #   requests
-importlib-metadata==4.6.3
+importlib-metadata==4.6.4
     # via
     #   -r docs/requirements.txt
     #   -r requirements.txt
@@ -314,6 +321,8 @@ pep517==0.11.0
     # via pip-tools
 pep8-naming==0.12.1
     # via -r requirements-dev.in
+pexpect==4.8.0
+    # via -r requirements-dev.in
 pip-tools==6.2.0
     # via -r requirements-dev.in
 platformdirs==2.2.0
@@ -322,6 +331,12 @@ pluggy==0.13.1
     # via pytest
 pre-commit==2.14.0
     # via -r requirements-dev.in
+prompt-toolkit==3.0.19
+    # via
+    #   -r requirements.txt
+    #   questionary
+ptyprocess==0.7.0
+    # via pexpect
 py==1.10.0
     # via
     #   pytest
@@ -343,8 +358,10 @@ pyflakes==2.3.1
 pygments==2.9.0
     # via
     #   -r docs/requirements.txt
+    #   -r requirements.txt
     #   flakehell
     #   mkdocs-material
+    #   rich
 pylint==2.9.6
     # via -r requirements-dev.in
 pymdown-extensions==8.2
@@ -410,6 +427,8 @@ pyyaml-env-tag==0.1
     # via
     #   -r docs/requirements.txt
     #   mkdocs
+questionary==1.10.0
+    # via -r requirements.txt
 regex==2021.8.3
     # via black
 repository-orm==0.5.3
@@ -419,6 +438,8 @@ requests==2.26.0
     #   -r docs/requirements.txt
     #   mkdocs-htmlproofer-plugin
     #   safety
+rich==10.7.0
+    # via -r requirements.txt
 ruamel.yaml==0.17.10
     # via -r requirements.txt
 ruamel.yaml.clib==0.2.6
@@ -499,6 +520,7 @@ typing-extensions==3.10.0.0
     #   mypy
     #   pydantic
     #   pytkdocs
+    #   rich
     #   tinydb
 urllib3==1.26.6
     # via
@@ -511,6 +533,10 @@ watchdog==2.1.3
     # via
     #   -r docs/requirements.txt
     #   mkdocs
+wcwidth==0.2.5
+    # via
+    #   -r requirements.txt
+    #   prompt-toolkit
 wheel==0.37.0
     # via
     #   -r docs/requirements.txt