Skip to content

Commit

Permalink
Bumped to version 2019.9.10.
Browse files Browse the repository at this point in the history 
Created `docs/` folder with documentation files, and initialized MkDocs.
Moved all content from `actionista/todoist/README.md` to these documentation files.
Added `DEVELOPMENT.md` with developer-relevant notes.
Added `requirements-dev.txt` with build dependencies.
Updated `setup.py`, bumped version to 2019.9.10, added `long_description_content_type='text/markdown'`, and changed description slightly.
Updated `MANIFEST.in` to include changed `README.md`.
Updated `__init__.py` with a brief package description, and bumped version to 2019.9.10.
  • Loading branch information
@scholer
scholer committed Sep 10, 2019
1 parent b6620ef commit 03f5a51
Show file tree
Hide file tree
Showing 13 changed files with 687 additions and 228 deletions.
3 changes: 3 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,3 +105,6 @@ ENV/

# Ignore notebooks/ for now:
notebooks/

# MkDocs static site HTML:
site/
109 changes: 109 additions & 0 deletions DEVELOPMENT.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@




Publishing:
-----------

Publishing takes the following steps:

1. Create distribution package and upload to PyPI.
2. Make a tagged release on GitHub.


### Create PyPI distribution release:


Create distribution package:

$ python setup.py sdist bdist_wheel

Perform basic local package checks (e.g. that the `long_description` will
render properly):

$ twine check dist/*

Test the package by uploading to test server, using either setuptools or twine:

$ twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Upload the distribution package to PyPI, using either setuptools or twine:

$ twine upload dist/*

OBS: You can also use good old setuptools to upload, but it may or may not be secure:

$ python setup.py upload dist/*

You can use a `.pypirc` file to store your PyPI credentials.
You can also set `TWINE_` environment variables, or use `keyring` package.


Refs:

* https://packaging.python.org/tutorials/packaging-projects/



#### Alternative options (not currently used):


Using `poetry`:

$ poetry publish


Using `flit`:

$ flit publish


Using `hatch`:

$ hatch release



### Create GitHub release:

Two options:

* Either go to https://github.com/scholer/actionista-todoist/releases and create a release.
* Or create an annotated git tag: `git tag -a <version>`, then push the tags to GitHub
using `git push --tags`.



Documentations:
---------------

Documentation options:

* Sphinx + ReadTheDocs - now with "reasonable" Markdown support.
* MkDocs + GitHub Pages.
* MkDocs builds Markdown documentation to static HTML, which can be served however you'd like,
e.g. with GitHub Pages.
* With GitHub pages, the docs lives in a separate branch of your
repository, `gh-pages` by default. You can publish docs with MkDocs directly to
gh-pages using `mkdocs gh-deploy`.
* You can also use MkDocs with ReadTheDocs:
https://read-the-docs.readthedocs.io/en/latest/intro/getting-started-with-mkdocs.html.




### MkDocs:

1. Init new project using: `mkdocs new .`
2. Edit `index.md` and add other doc files.
3. Serve locally, `mkdocs serve`.
4. Edit `mkdocs.yml`, updating `site_name:` and `nav:` (and optionally `theme:`).
5. Build: `mkdocs build`.
* Add `site/` to `.gitignore` if you haven't done so already.
`echo "site/" >> .gitignore`.
6. Deploy as GitHub Pages: `mkdocs gh-deploy`.
7. Alternatively, configure your ReadTheDocs to import your




2 changes: 1 addition & 1 deletion MANIFEST.in
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
include README.rst
include README.md
include LICENSE
10 changes: 9 additions & 1 deletion actionista/__init__.py
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,12 @@
"""
Actionista Action CLI for Todoist (actionista-todoist).
A `find`-inspired CLI for Todoist.
Add, select, print, reschedule, modify, and complete tasks in a batch-wise fashion
from the command line.
"""

# Do not zero-pad month or day:
__version__ = '2019.9.9' # remember to also update setup.py
__version__ = '2019.9.10' # remember to also update setup.py
228 changes: 6 additions & 222 deletions actionista/todoist/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,10 @@

Please see `docs/index.md` for end-user documentation for
the CLI programs found within this package.




Actionista Action CLI for Todoist
==================================

Expand All @@ -17,225 +23,3 @@ You start out with a list of *all* tasks, and then select tasks using one of the
filters available. You can then sort, print, and reschedule the selected tasks.


Configuration:
--------------

In order to use the Todoist API, you need to configure an API access token.
You can use the `actionista-todoist-config` CLI to set this up.

You can run the full interactive configuration using:

$ actionista-todoist-config --interactive

Alternatively, if you just need to update your API token, you can run:

$ actionista-todoist-config --check-token --token 41f1c812be19cc3bcee6c6c2a569c545f7bfd7e1

(Replace `41f1c812be19cc3bcee6c6c2a569c545f7bfd7e1` with your actual API token.)

You can find your API token in the Todoist web app, under 'Settings' -> 'Integrations',
or by browsing directly to this page: https://todoist.com/prefs/integrations
(working directions as of September 2019).


Examples:
---------

> OBS: In all examples, a code line starting with `$ ` means that it should be run from
> the terminal / command prompt.
### Basic actions:

The basic actions are:

* `-sync` - make sure you have the latest updates from the Todoist server.
* `-print` - used to print tasks out (in the terminal).
* `-commit` - used to submit any changes that you've made.

Almost all examples starts with a `-sync` action,
followed by one or more task selection (filtering) actions,
followed by a `-sort` action to sort the selected tasks,
then a `-print` action to print the selected tasks out.

If you want to make changes, e.g. close or reschedule the selected tasks,
you just add the desired action command (e.g. `-close` or `-reschedule "tomorrow"),
followed by `-commit` to submit your changes to the server.

*Please make sure to remember the `-commit` action, if you want your changes to have any effect!*




### Selecting tasks:

You typically use the following actions for selecting (filtering) tasks:

* `-name "task-content"` - select tasks by the task name ("content").
* `-project "project-name"` - select tasks in a given project.
* `-due [before/after "date"]` - select tasks by due date.
* `-is [not] recurring` - select recurring or non-recurring tasks.

You can use "glob patterns" when selecting tasks by task name or project.
For instance, `-project "Dev*"` will select tasks for all projects that begin with "Dev".

For more info on "glob pattern matching", see e.g. [this](https://facelessuser.github.io/wcmatch/glob/)
or [wikipedia](https://en.wikipedia.org/wiki/Glob_(programming)).

Additional convenience actions to filter/select tasks by task name:

* `-contains "text"` - the same as `-name "*text*"`.
* `-startswith "text"` - the same as `-name "text*"`.
* `-endswith "text"` - the same as `-name "*text"`.


#### Task selection examples:

Print all tasks in your "Work" project.

$ todoist-action-cli -sync -project "Work" -sort -print

To select tasks in both "Work", as well as "Work-dev" and "Work-admin",
just add an asterix after "Work". This will use "glob-style" pattern matching:

$ todoist-action-cli -sync -project "Work*" -sort -print


### Sorting tasks:

Sort overdue tasks by due date:

$ todoist-action-cli -due before today -sort "due_date_safe_dt" -print

Sort overdue tasks by priority, then due date, then project:

$ todoist-action-cli -due before today -sort "priority_str,due_date_safe_dt,project_name" -print

* Note: We sort by "priority_str" (p1, p2, ...), since we are sorting in "ascending" mode by default,
and priority_str gets the highest-priority tasks at the top.
We could sort by "priority", but for "priority", higher values means "higher priority",
while for "priority_str", a "p1" priority is higher than "p3".


### Closing/completing tasks:

Close (complete) a task starting with "Write" from project "Personal" (and also print the task):

$ todoist-action-cli -sync -project "Personal" -startswith "Write" -print -close -commit

After invoking the command above, you should now see the task as being "checked off" when you print it:

$ todoist-action-cli -sync -project "Personal" -startswith "Write" -sort -print

You can re-open the task again, if you need to:

$ todoist-action-cli -sync -project "Personal" -startswith "Write" -print -reopen -commit


### Rescheduling tasks:

Reschedule task "Task123" (and also print the task):

$ todoist-action-cli -sync -name "Task123" -print -reschedule "tomorrow" -commit

After invoking the command above, you should see that the task due day has changed when you print it:

$ todoist-action-cli -sync -name "Task123" -print

You can generally specify dates and times the same way you would in Todoist,
e.g. using "2 days from now", "Wednesday 3 pm", "next monday", "2019-12-31 15:00", etc.


### Adding new tasks:

To add a new task, use the `-add-task` action:


You can add labels like you normally would using `@label`:

$ todoist-action-cli -sync -add-task "Test task 005 @devtest #Dev-personal <date tomorrow> p2" -commit

However, as you can see, using "#project" and the normal ways of specifying due date and priority doesn't work.

You can provide information on `project`, `due` date, `priority`, and `labels` explicitly using `key=value` notation:

$ todoist-action-cli -sync -add-task "Test task 006" project=Work due=tomorrow priority=p1 \
labels=awaiting,devtest -commit -filter content startswith "Test" -print "{content}"


### Rename a task:

To rename an existing task, first select it using one or more filters, then use the `-rename` action.
For example:

$ todoist-action-cli -label devtest -content "Test task 1435" -sort -print -rename "Test task 1850" -commit

Then check that it has been renamed:

$ todoist-action-cli -label devtest -content "Test task *" -sort -print


### Showing changes before they are submitted:

If you are curious about what changes will be submitted to the server, you can see them before you `-commit`,
using `-show-queue` action:

$ todoist-action-cli -sync -name "Task123" -print -reschedule "tomorrow" -show-queue -commit

$ todoist-action-cli -sync -add-task "Test task 006" project=Work due=tomorrow priority=p1 labels=awaiting,devtest -show-queue fmt=json -commit


### Resetting cached data:

You may encounter a state that does not allow you to continue using `todoist-action-cli` or the todoist-python package.
If that happens, you can run the following command to delete the cache, thereby resetting the local state:

$ todoist-action-cli inject_task_date_fields=0 inject_task_project_fields=0 -delete-cache

*OBS: If this happens, it may be due to a bug in this program.
If so, please consider submitting an issue at https://github.com/scholer/actionista-todoist/issues.
If you are technically proficiency and you have managed to fix a bug in this program,
I welcome you to submit a pull-request at https://github.com/scholer/actionista-todoist/pulls.*


Alternative Todoist CLI:
========================

This package also provides a more "traditional" CLI for Todoist.

The traditional CLI currently provides the following features:

* `add-task` - which can be used to add a new task to Todoist.
* `print-projects` - which can be used to print your Todoist projects.



Examples:
---------

### Example: Add a new task:

Add a task:

$ todoist-cli add-task "Test task 1234"

Add a task, specifying due-date, project, labels, priority, and a note:

$ todoist-cli add-task "Test task 1235 @devtest" --due "tomorrow 2 pm" --project "Todoist-playground" --label "playground" --priority p4 --note "This is a third note"

As you can see, you can add labels using "@label" as you do in the Todoist web-app,
or using `--label <label>`. The following three commands are all equivalent:

$ todoist-cli add-task "Test task 1235" --label "playground" --label devtest
$ todoist-cli add-task "Test task 1235 @devtest" --label "playground"
$ todoist-cli add-task "Test task 1235 @devtest @playground"

Note that `todoist-cli add-task` is equivalent to `todoist-add-task`.
You can use whichever format you prefer.


### Example: Print projects

You can use the `print-projects` CLI command to print your Todoist projects:

$ todoist-cli print-projects

Loading

0 comments on commit 03f5a51

Please sign in to comment.