Diff

from v0.3.5 to v0.3.6

Diffstat

 .coveragerc | 6 
 .gitignore | 3 
 CHANGELOG.rst | 161 ++++++
 CHANGELOG.txt | 102 ----
 CONTRIBUTING.rst | 93 +++
 LICENSE | 2 
 Makefile | 102 +--
 Pipfile | 27 -
 README.rst | 91 ---
 TODO.txt | 1 
 docs/Makefile | 2 
 docs/source/changelog.rst | 1 
 docs/source/conf.py | 74 ++
 docs/source/configuration.rst | 632 ------------------------
 docs/source/configuration/colors.rst | 205 ++++++++
 docs/source/configuration/genopts.rst | 157 ++++++
 docs/source/configuration/intro.rst | 3 
 docs/source/configuration/keybindings.rst | 254 ++++++++++
 docs/source/contributing.rst | 3 
 docs/source/index.rst | 33 
 docs/source/nncli-cat.1.rst | 27 +
 docs/source/nncli-create.1.rst | 22 
 docs/source/nncli-delete.1.rst | 22 
 docs/source/nncli-dump.1.rst | 22 
 docs/source/nncli-edit.1.rst | 22 
 docs/source/nncli-export.1.rst | 27 +
 docs/source/nncli-favorite.1.rst | 22 
 docs/source/nncli-import.1.rst | 22 
 docs/source/nncli-list.1.rst | 22 
 docs/source/nncli-sync.1.rst | 17 
 docs/source/nncli.1.rst | 53 +
 docs/source/nncli.config.5.rst | 56 ++
 docs/source/usage.rst | 220 +-------
 docs/source/usage/cat-args.rst | 3 
 docs/source/usage/cat-desc.rst | 4 
 docs/source/usage/cat-example.rst | 11 
 docs/source/usage/create-desc.rst | 3 
 docs/source/usage/create-example.rst | 7 
 docs/source/usage/delete-args.rst | 3 
 docs/source/usage/delete-desc.rst | 1 
 docs/source/usage/dump-args.rst | 8 
 docs/source/usage/dump-desc.rst | 6 
 docs/source/usage/edit-args.rst | 3 
 docs/source/usage/edit-desc.rst | 2 
 docs/source/usage/export-args.rst | 8 
 docs/source/usage/export-desc.rst | 11 
 docs/source/usage/export-example.rst | 10 
 docs/source/usage/favorite-args.rst | 3 
 docs/source/usage/favorite-desc.rst | 1 
 docs/source/usage/genopts.rst | 24 
 docs/source/usage/import-desc.rst | 5 
 docs/source/usage/import-example.rst | 4 
 docs/source/usage/list-args.rst | 4 
 docs/source/usage/list-desc.rst | 4 
 docs/source/usage/subopts.rst | 23 
 docs/source/usage/sync-desc.rst | 3 
  | 2 
  | 0 
  | 16 
  | 0 
  | 0 
  | 0 
  | 0 
  | 0 
  | 37 +
  | 4 
  | 0 
  | 0 
  | 0 
  | 0 
  | 0 
  | 0 
  | 0 
 pyproject.toml | 106 +++
 pytest.ini | 2 
 requirements-dev.txt | 531 +++++++++++++++++++++
 requirements.txt | 37 +
 tox.ini | 34 -

.coveragerc (deleted)

1 -[run]
2 -branch = True
3 -omit = nncli/__main__.py
4 -
5 -[report]
6 -show_missing = True

.gitignore

7 7 docs/build/
8 8 .tox
9 9 htmlcov/
10 -Pipfile.lock
10 +docs/html/
11 +docs/man/

CHANGELOG.rst (created)

1 +Changelog
2 +=========
3 +
4 +All notable changes to this project will be documented in this file.
5 +
6 +The format is based on `Keep a Changelog`_, and this project adheres to
7 +`Semantic Versioning`_.
8 +
9 +`Unreleased`_
10 +-------------
11 +Changed
12 +
13 +Added
14 +
15 +Fixed
16 +
17 +Removed
18 +
19 +`v0.3.6`_ - 2022-12-30
20 +----------------------
21 +Changed
22 + - docs: Major refactor to provide manual pages
23 + - docs: Change to material theme
24 + - README: Add reference to mailing list
25 + - Update pyproject.toml
26 + - Convert Makefiles to POSIX style
27 + - consolidate tool configs in pyproject.toml
28 + - update requirements-dev.txt
29 + - cli: Modify edit to accept from_stdin flag
30 +
31 +Added
32 + - Add community guidelines
33 + - Add stdin flag to edit subcommand
34 + - Add TODO
35 +
36 +Fixed
37 + - cli: Fix (un)favorite
38 + - nncli: Always check do_server_sync before syncing
39 +
40 +Removed
41 + - docs: Remove CI badge
42 + - docs: Don't build PDF
43 + - Remove Pipenv in favor of the simpler pip-tools
44 +
45 +`v0.3.5`_ - 2021-12-10
46 +----------------------
47 +Changed
48 + - Update copyright info in docs
49 + - Make filtered_notes_sort public
50 + - Use $VISUAL instead of $EDITOR
51 + - clipboard: Silence calls to 'which'
52 + - Smarten up the way we set defaults for cfg_editor
53 + - Add mailmap
54 + - Allow syncing in Python 3.8 and later
55 + - Constrain pytest version
56 +
57 +Added
58 + - clipboard: Add support for xclip
59 + - Add initial hack at a manual
60 + - Tox: Add py38 testing
61 +
62 +Fixed
63 + - Fixed 'nncli create' to work without any arguments (credit: lifesbest23)
64 + - clipboard: Fix line continuations
65 +
66 +
67 +`v0.3.4`_ - 2019-03-08
68 +----------------------
69 +Changed
70 + - Fix crashing bug in view_log.py
71 + - Refactor gui.py based on pylint findings
72 +
73 +Removed
74 + - Pipfile.lock
75 +
76 +`v0.3.3`_ - 2019-02-25
77 +----------------------
78 +Added
79 + - Documentation
80 +
81 + - TODO and CHANGELOG formatting
82 + - docutils.conf
83 + - sitemap
84 + - Canonical URL
85 + - robots.txt
86 +
87 +Changed
88 + - Changed SafeConfigParser to ConfigParser
89 + - Reversed test logic in _log_timeout to avoid popping off on an empty
90 + stack. This bug was leading to fatal crashes.
91 +
92 +`v0.3.2`_ – 2018-12-01
93 +----------------------
94 +Added
95 + - CHANGELOG.rst
96 + - TODO.txt
97 + - clear_ids.py contrib script
98 +
99 +Changed
100 + - References to Github repo changed to point to git.danielmoch.com
101 + - Fixed exception in nncli sync
102 +
103 +`v0.3.1`_ – 2018-10-30
104 +----------------------
105 +Added
106 + - Partial unit testing for nncli.py module
107 +
108 +Changed
109 + - Refactored code (addressing pylint findings)
110 + - Fixed bad exception handling in Python 3.4
111 +
112 +`v0.3.0`_ – 2018-09-07
113 +----------------------
114 +Added
115 + - Documentation as PDF format
116 +
117 +Changed
118 + - Numerous documentation corrections
119 +
120 +`v0.2.0`_ – 2018-09-03
121 +----------------------
122 +Added
123 + - .travis.yml
124 + - Pytest, tox, et all added to support automated testing
125 + - Both tox and Travis testing back to Python 3.4
126 +
127 +`v0.1.2`_ – 2018-08-30
128 +----------------------
129 +Added
130 + - Support for --version flag
131 +
132 +Changed
133 + - requirements.txt replaced with Pipfile{,.lock}
134 +
135 +`v0.1.1`_ – 2018-08-07
136 +----------------------
137 +Added
138 + - README content included in PyPI
139 +
140 +Changed
141 + - README content and formatting
142 + - Fix nncli import command
143 +
144 +v0.1.0 – 2018-07-31
145 +-------------------
146 +Changed
147 + - Hard fork of sncli
148 +
149 +.. _Keep a Changelog: https://keepachangelog.com/en/1.0.0/
150 +.. _Semantic Versioning: https://semver.org/spec/v2.0.0.html
151 +.. _Unreleased: https://git.danielmoch.com/nncli/diff/?id=master&id2=v0.3.6
152 +.. _v0.3.6: https://git.danielmoch.com/nncli/diff/?id=v0.3.6&id2=v0.3.5
153 +.. _v0.3.5: https://git.danielmoch.com/nncli/diff/?id=v0.3.5&id2=v0.3.4
154 +.. _v0.3.4: https://git.danielmoch.com/nncli/diff/?id=v0.3.4&id2=v0.3.3
155 +.. _v0.3.3: https://git.danielmoch.com/nncli/diff/?id=v0.3.3&id2=v0.3.2
156 +.. _v0.3.2: https://git.danielmoch.com/nncli/diff/?id=v0.3.2&id2=v0.3.1
157 +.. _v0.3.1: https://git.danielmoch.com/nncli/diff/?id=v0.3.1&id2=v0.3.0
158 +.. _v0.3.0: https://git.danielmoch.com/nncli/diff/?id=v0.3.0&id2=v0.2.0
159 +.. _v0.2.0: https://git.danielmoch.com/nncli/diff/?id=v0.2.0&id2=v0.1.2
160 +.. _v0.1.2: https://git.danielmoch.com/nncli/diff/?id=v0.1.2&id2=v0.1.1
161 +.. _v0.1.1: https://git.danielmoch.com/nncli/diff/?id=v0.1.1&id2=v0.1.0

CHANGELOG.txt (deleted)

1 -Changelog
2 -=========
3 -
4 -All notable changes to this project will be documented in this file.
5 -
6 -The format is based on Keep a Changelog [1] , and this project adheres to
7 -Semantic Versioning [2].
8 -
9 -Unreleased [3]
10 -----------
11 -
12 -v0.3.4 - 2019-03-08 [4]
13 --------------------
14 -Changed
15 - - Fix crashing bug in view_log.py
16 - - Refactor gui.py based on pylint findings
17 -
18 -Removed
19 - - Pipfile.lock
20 -
21 -v0.3.3 - 2019-02-25 [5]
22 --------------------
23 -Added
24 -- Documentation
25 - - TODO and CHANGELOG formatting
26 - - docutils.conf
27 - - sitemap
28 - - Canonical URL
29 - - robots.txt
30 -
31 -Changed
32 -- Changed SafeConfigParser to ConfigParser
33 -- Reversed test logic in _log_timeout to avoid popping off on an empty
34 - stack. This bug was leading to fatal crashes.
35 -
36 -v0.3.2 – 2018-12-01 [6]
37 --------------------
38 -Added
39 - - CHANGELOG.rst
40 - - TODO.txt
41 - - clear_ids.py contrib script
42 -
43 -Changed
44 -- References to Github repo changed to point to git.danielmoch.com
45 -- Fixed exception in nncli sync
46 -
47 -v0.3.1 – 2018-10-30 [7]
48 --------------------
49 -Added
50 -- Partial unit testing for nncli.py module
51 -
52 -Changed
53 -- Refactored code (addressing pylint findings)
54 -- Fixed bad exception handling in Python 3.4
55 -
56 -v0.3.0 – 2018-09-07 [8]
57 --------------------
58 -Added
59 -- Documentation as PDF format
60 -
61 -Changed
62 -- Numerous documentation corrections
63 -
64 -v0.2.0 – 2018-09-03 [9]
65 --------------------
66 -Added
67 -- .travis.yml
68 -- Pytest, tox, et all added to support automated testing
69 -- Both tox and Travis testing back to Python 3.4
70 -
71 -v0.1.2 – 2018-08-30 [10]
72 --------------------
73 -Added
74 -- Support for --version flag
75 -
76 -Changed
77 -- requirements.txt replaced with Pipfile{,.lock}
78 -
79 -v0.1.1 – 2018-08-07 [11]
80 --------------------
81 -Added
82 -- README content included in PyPI
83 -
84 -Changed
85 -- README content and formatting
86 -- Fix nncli import command
87 -
88 -v0.1.0 – 2018-07-31
89 --------------------
90 -- Hard fork of sncli
91 -
92 -[1] - https://keepachangelog.com/en/1.0.0/
93 -[2] - https://semver.org/spec/v2.0.0.html
94 -[3] - https://git.danielmoch.com/nncli/diff/?id=master&id2=v0.3.4
95 -[4] - https://git.danielmoch.com/nncli/diff/?id=v0.3.4&id2=v0.3.3
96 -[5] - https://git.danielmoch.com/nncli/diff/?id=v0.3.3&id2=v0.3.2
97 -[6] - https://git.danielmoch.com/nncli/diff/?id=v0.3.2&id2=v0.3.1
98 -[7] - https://git.danielmoch.com/nncli/diff/?id=v0.3.1&id2=v0.3.0
99 -[8] - https://git.danielmoch.com/nncli/diff/?id=v0.3.0&id2=v0.2.0
100 -[9] - https://git.danielmoch.com/nncli/diff/?id=v0.2.0&id2=v0.1.2
101 -[10] - https://git.danielmoch.com/nncli/diff/?id=v0.1.2&id2=v0.1.1
102 -[11] - https://git.danielmoch.com/nncli/diff/?id=v0.1.1&id2=v0.1.0

CONTRIBUTING.rst (created)

1 +Contribution Guide
2 +==================
3 +
4 +Thanks for your interest in contributing to nncli(1). This guide
5 +attempts to document everything you need to know to participate in the
6 +development community. As with everything else in this repository,
7 +suggestions are welcome.
8 +
9 +Community Guidelines
10 +--------------------
11 +
12 +Given that the nncli(1) community is still in the early stages of
13 +formation, community guidelines have yet to be rigidly codified. For
14 +the time being, the following general expectations should be
15 +considered normative:
16 +
17 +- Participants should do their part to make this a welcoming
18 + community, free from harassment and discrimination, where everyone
19 + feels safe to contribute. Any behavior that threatens this will not
20 + be tolerated, and repeated violations will result in expulsion from
21 + the community. Anyone who egregiously violates this principle, for
22 + instance by doxxing another community member, whether in official
23 + community channels or elsewhere, will be immediately and permanently
24 + banned.
25 +
26 +- The goal in providing official community channels (e.g., the mailing
27 + list), is to provide a public space for the development of nncli(1)
28 + with high signal-to-noise ratio. Persuant to this, community members
29 + should understand that disagreements naturally arise from time to
30 + time. If they don't pertain to nncli(1), then they should be
31 + discussed outside official community channels. This is not a
32 + judgment about the importance of any given topic, merely a
33 + recognition that this community cannot sustain discussion about
34 + anything and everything.
35 +
36 +- Maintainers shall be selected from the community as-needed based on
37 + their ability to productively contribute to nncli(1). Productivity
38 + in this context is measured *both* in terms of code contributions
39 + *and* ability to forge consensus in community discussions.
40 +
41 +- Decisions regarding the development of nncli(1) fall to the
42 + maintainers collectively. When the maintainers are not able to form
43 + a consensus on the best path forward, the lead maintainer shall be
44 + the final authority on decisions.
45 +
46 +Getting Started
47 +---------------
48 +
49 +To get started with the code, you will need to clone it and install
50 +development dependencies. We recommend the isolating your development
51 +environment with ``venv`` Python module. We also recommend using
52 +``pip-tools`` to manage dependencies. Its use is expected when
53 +updating requirements files.
54 +
55 +::
56 +
57 + $ git clone https://git.danielmoch.com/nncli.git
58 + $ cd nncli
59 + $ python3 -m venv .venv
60 + $ source .venv/bin/activate
61 + (.venv)$ pip install pip-tools
62 + (.venv)$ pip-sync requirements-dev.txt
63 +
64 +Discussion and Requests
65 +-----------------------
66 +
67 +All discussion takes place on the public `mailing list`_. The list's
68 +archive can be found at https://lists.danielmoch.com/nncli-dev. Emails
69 +can be sent to the following addresses to manage your subscription to
70 +the mailing list.
71 +
72 +- nncli-dev+subscribe@
73 +- nncli-dev+unsubscribe@
74 +- nncli-dev+help@
75 +
76 +Patches and pull requests are welcome, preferably via emailed output
77 +of `git-request-pull(1)`_ sent to the mailing list. Bug reports should
78 +also be directed to the mailing list.
79 +
80 +If you aren't hosting a fork anywhere online, you can also send patches
81 +using `git-format-patch(1)`_.
82 +
83 +Releases
84 +--------
85 +
86 +Releases are published to PyPI_. Signed source tarballs are maintained
87 +at https://dl.danielmoch.com/nncli. Instructions for verifying
88 +tarballs are in the README file at the previous link.
89 +
90 +.. _PyPI: https://pypi.org/project/nncli/
91 +.. _mailing list: nncli-dev@danielmoch.com
92 +.. _git-format-patch(1): https://www.git-scm.com/docs/git-format-patch
93 +.. _git-request-pull(1): https://www.git-scm.com/docs/git-request-pull

LICENSE

1 1
2 2 The MIT License (MIT)
3 3
4 -Copyright (c) 2018 Daniel Moch
4 +Copyright (c) 2018-2022 Daniel Moch
5 5
6 6 Permission is hereby granted, free of charge, to any person obtaining a copy
7 7 of this software and associated documentation files (the "Software"), to deal

Makefile

1 -.PHONY: clean clean-test clean-pyc clean-build help lint coverage coverage-html release dist install run debug docs
2 -.DEFAULT_GOAL := help
1 +.POSIX:
3 2
4 -define BROWSER_PYSCRIPT
5 -import os, webbrowser, sys
6 -
7 -try:
8 - from urllib import pathname2url
9 -except:
10 - from urllib.request import pathname2url
11 -
12 -webbrowser.open("file://" + pathname2url(os.path.abspath(sys.argv[1])))
13 -endef
14 -export BROWSER_PYSCRIPT
3 +.PHONY: clean clean-test clean-pycache clean-build help lint coverage coverage-html release dist install run debug docs
15 4
16 -define PRINT_HELP_PYSCRIPT
17 -import re, sys
5 +dist:
6 + flit build
18 7
19 -for line in sys.stdin:
20 - match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line)
21 - if match:
22 - target, help = match.groups()
23 - print("%-20s %s" % (target, help))
24 -endef
25 -export PRINT_HELP_PYSCRIPT
26 -
27 -BROWSER := python -c "$$BROWSER_PYSCRIPT"
28 -PIPENV := pipenv
29 -PIPRUN := $(PIPENV) run
30 -PIPINST := $(PIPENV) --bare install --dev --skip-lock
31 -
32 -help:
33 - @python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
34 -
35 -clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts
8 +clean: clean-build clean-pycache clean-test
36 9 make -C docs clean
37 10
38 -clean-build: ## remove build artifacts
39 - rm -fr build/
11 +clean-build:
40 12 rm -fr dist/
41 - rm -fr .eggs/
42 - find . -name '*.egg-info' -exec rm -fr {} +
43 - find . -name '*.egg' -exec rm -f {} +
44 13
45 -clean-pyc: ## remove Python file artifacts
46 - find . -name '*.pyc' -exec rm -f {} +
47 - find . -name '*.pyo' -exec rm -f {} +
48 - find . -name '*~' -exec rm -f {} +
14 +clean-pycache:
49 15 find . -name '__pycache__' -exec rm -fr {} +
50 - $(PIPRUN) pip uninstall -y nncli
51 16
52 -clean-test: ## remove test and coverage artifacts
17 +clean-test:
53 18 rm -f .coverage
54 19 rm -fr htmlcov/
55 20 rm -fr .pytest_cache
56 21 rm -fr .tox
57 22
58 -lint: ## check style with pylint
59 - $(PIPRUN) pylint nncli tests --disable=parse-error
60 - $(PIPRUN) vulture nncli .vulture_whitelist.py
23 +lint:
24 + pylint nncli tests --disable=parse-error
25 + vulture nncli .vulture_whitelist.py
61 26
62 -test: ## run tests quickly with the default Python
63 - $(PIPRUN) python -m pytest
27 +test:
28 + python -m pytest
64 29
65 -test-all: ## run tests on every Python version with tox
66 - $(PIPRUN) tox
30 +test-all:
31 + tox
67 32
68 -test-install: ## install dependenices from Pipfile (for tox / CI builds)
69 - $(PIPINST)
33 +coverage:
34 + python -m pytest --cov=nncli
70 35
71 -coverage: ## check code coverage quickly with the default Python
72 - $(PIPRUN) python -m pytest --cov=nncli
36 +coverage-html: coverage
37 + coverage html
73 38
74 -coverage-html: coverage ## generate an HTML report and open in browser
75 - $(PIPRUN) coverage html
76 - $(BROWSER) htmlcov/index.html
77 -
78 -release: dist ## package and upload a release
39 +release: dist
79 40 twine upload -s dist/*
80 41
81 -dist: ## builds source and wheel package
82 - $(PIPRUN) flit build
83 - ls -l dist
42 +docs:
43 + make -C docs html man
84 44
85 -docs: ## builds the sphinx documentation and opens in the browser
86 - make -C docs html
87 - make -C docs latexpdf
88 - make -C docs man
89 - $(BROWSER) docs/build/html/index.html
45 +install:
46 + flit install --deps=none
90 47
91 -install: ## install the package to the active Python's site-packages
92 - $(PIPRUN) flit install --deps=none
93 -
94 -run: ## run the package from site-packages
95 - $(PIPRUN) python -m nncli $(cmd)
48 +run:
49 + python -m nncli $(cmd)
96 50
97 -debug: install ## debug the package from site packages
98 - $(PIPRUN) pudb3 $$($(PIPRUN) which nncli) $(cmd)
51 +debug: install
52 + pudb3 $$(which nncli) $(cmd)

Pipfile (deleted)

1 -[[source]]
2 -url = "https://pypi.org/simple"
3 -verify_ssl = true
4 -name = "pypi"
5 -
6 -[packages]
7 -appdirs = "*"
8 -requests = "*"
9 -urwid = "*"
10 -click = "*"
11 -
12 -[dev-packages]
13 -pytest = ">=5.2,<5.3"
14 -pytest-cov = "*"
15 -pytest-mock = "*"
16 -pylint = "*"
17 -pudb = "*"
18 -sphinx = "*"
19 -flit = "*"
20 -setuptools = "*"
21 -mock = "*"
22 -tox = "*"
23 -pathlib2 = {version = "*",markers = "python_version < '3.5'"}
24 -scandir = {version = "*",markers = "python_version < '3.5'"}
25 -vulture = "*"
26 -sphinx-rtd-theme = "*"
27 -sphinx-sitemap = "*"

README.rst

1 -nncli is a Python application that gives you access to your NextCloud
1 +``nncli`` is a Python application that gives you access to your NextCloud
2 2 Notes account via the command line. It's a "hard" fork of
3 3 sncli_. You can access your notes via
4 4 a customizable console GUI that implements vi-like keybinds or via a
. . .
10 10
11 11 More detailed documentation can be found at the homepage_.
12 12
13 -Requirements
14 -------------
15 -
16 -- `Python 3`_
17 -
18 -- Urwid_ Python 3 module
19 -
20 -- Requests_ Python 3 module
21 -
22 -- A love for the command line!
23 -
24 13 Installation
25 14 ------------
26 15
27 -- Via pip (latest release):
28 -
29 - - ``pip3 install nncli``
30 -
31 -- Manually:
32 -
33 - - If you don't already have it, install Flit_: ``pip3 install flit``
34 -
35 - - Clone this repository to your hard disk: ``git clone
36 - https://git.danielmoch.com/nncli.git``
37 -
38 - - Install nncli: ``flit install --deps production``
39 -
40 -- Development:
16 +Assuming your system has both ``python3`` and ``pip3``, you can
17 +globally install ``nncli`` and its dependencies with ``pip3 install
18 +nncli``.
41 19
42 - - Clone the repo
43 -
44 - - Install Pipenv: ``pip3 install pipenv``
45 -
46 - - Stand up development virtualenv: ``pipenv install --dev``
20 +If you are interested in packaging ``nncli`` for various
21 +distributions, please consult the file CONTRIBUTING.rst_ in this
22 +repository and reach out to the mailing list with any questions.
47 23
48 24 Features
49 25 --------
. . .
52 28
53 29 - full two-way sync with NextCloud Notes performed dynamically in the
54 30 background
55 -
56 31 - all actions logged and easily reviewed
57 -
58 32 - list note titles (configurable format w/ title, date, flags, category,
59 33 keys, etc)
60 -
61 34 - sort notes by date, alpha by title, category, favorite on top
62 -
63 35 - search for notes using a Google style search pattern or Regular
64 36 Expression
65 -
66 37 - view note contents and meta data
67 -
68 38 - pipe note contents to external command
69 -
70 39 - create and edit notes (using your editor)
71 -
72 40 - edit note category
73 -
74 41 - delete notes
75 -
76 42 - favorite/unfavorite notes
77 -
78 43 - vi-like keybinds (fully configurable)
79 -
80 44 - Colors! (fully configurable)
81 45
82 46 - Command Line (scripting)
83 47
84 48 - force a full two-way sync with NextCloud Notes
85 -
86 49 - all actions logged and easily reviewed
87 -
88 50 - list note titles and keys
89 -
90 51 - search for notes using a Google style search pattern or Regular
91 52 Expression
92 -
93 53 - dump note contents
94 -
95 54 - create a new note (via stdin or editor)
96 -
97 55 - import a note with raw json data (stdin or editor)
98 -
99 56 - edit a note (via editor)
100 -
101 57 - delete a note
102 -
103 58 - favorite/unfavorite a note
104 -
105 59 - view and edit note category
106 60
107 -Contributing
108 -------------
109 -
110 -Pull requests are welcome, preferably via emailed output of ``git
111 -request-pull`` sent to the maintainer (see here_ for more information).
112 -Bug reports should also be directed to the maintainer via email_.
113 -
114 -If you aren't hosting a fork anywhere online, you can also send patches
115 -using ``git format-patch`` (again, see `the official documentation`_ ).
116 -
117 -Releases
118 ---------
119 -
120 -Release tags will always be signed with the maintainer's `PGP key`_
121 -(also available on any public keyserver_). PGP-signed versions of
122 -release tarballs and pre-built wheel_ packages are available on PyPI_,
123 -with the signature files living alongside the corresponding artifact
124 -(simply append an ``.asc`` extension). Because the maintainers of PyPI
125 -do not consider PGP signatures to be a user-facing feature, the
126 -extension must be added manually in your browser's URL bar in order to
127 -download the signature files.
128 -
129 61 Acknowledgements
130 62 ----------------
131 63
. . .
135 67
136 68 .. _homepage: https://nncli.org
137 69 .. _sncli: https://github.com/insanum/sncli
70 +.. _CONTRIBUTING.rst: https://git.danielmoch.com/nncli/tree/CONTRIBUTING.rst
138 71 .. _Python 3: http://python.org
139 72 .. _Urwid: http://urwid.org
140 73 .. _Requests: https://requests.readthedocs.org/en/master
141 74 .. _simplenote.py: https://github.com/mrtazz/simplenote.py
142 75 .. _nvpy: https://github.com/cpbotha/nvpy
143 -.. _Flit: https://flit.readthedocs.io
144 -.. _here: https://www.git-scm.com/docs/git-request-pull
145 -.. _PGP key: https://www.danielmoch.com/static/gpg.asc
146 -.. _wheel: https://pythonwheels.com/
147 -.. _PyPI: https://pypi.org/project/nncli/
148 -.. _keyserver: https://pgp.mit.edu/pks/lookup?op=get&search=0x323C9F1784BDDD43
149 -.. _email: daniel@danielmoch.com
150 -.. _the official documentation: https://www.git-scm.com/docs/git-format-patch

TODO.txt

1 1 TODO
2 2 ----
3 +- Support NextCloud Notes v1.0 API
3 4 - Create a proper groff manual
4 5 - Address duplicate code (pylint finding)
5 6 - Target 80% unit test coverage

docs/Makefile

3 3
4 4 # You can set these variables from the command line.
5 5 SPHINXOPTS =
6 -SPHINXBUILD = pipenv run sphinx-build
6 +SPHINXBUILD = sphinx-build
7 7 SPHINXPROJ = nncli
8 8 SOURCEDIR = source
9 9 BUILDDIR = build

docs/source/changelog.rst (created)

1 +.. include:: ../../CHANGELOG.rst

docs/source/conf.py

14 14 #
15 15 import os
16 16 import sys
17 -sys.path.insert(0, os.path.abspath(os.path.sep.join(['..', '..'])))
17 +sys.path.insert(0, os.path.abspath(os.path.sep.join(['..', '..', 'src'])))
18 18 import nncli
19 19
20 20 # -- Project information -----------------------------------------------------
21 21
22 22 project = 'nncli'
23 -copyright = '2018-2019, Daniel Moch'
23 +copyright = '2018-2022, Daniel Moch'
24 24 author = 'Daniel Moch'
25 25
26 26 # The short X.Y version
. . .
54 54 # source_suffix = ['.rst', '.md']
55 55 source_suffix = '.rst'
56 56
57 -# The master toctree document.
58 -master_doc = 'index'
59 -
60 57 # The language for content autogenerated by Sphinx. Refer to documentation
61 58 # for a list of supported languages.
62 59 #
. . .
67 64 # List of patterns, relative to source directory, that match files and
68 65 # directories to ignore when looking for source files.
69 66 # This pattern also affects html_static_path and html_extra_path .
70 -exclude_patterns = []
67 +exclude_patterns = ['usage/*', 'configuration/*']
71 68
72 69 # The name of the Pygments (syntax highlighting) style to use.
73 -pygments_style = 'sphinx'
70 +pygments_style = 'bw'
74 71
75 72
76 73 # -- Options for HTML output -------------------------------------------------
. . .
78 75 # The theme to use for HTML and HTML Help pages. See the documentation for
79 76 # a list of builtin themes.
80 77 #
81 -html_theme = 'sphinx_rtd_theme'
78 +html_theme = 'sphinx_material'
82 79 html_extra_path = ['robots.txt']
83 80
84 81 html_baseurl = 'https://nncli.org/'
. . .
88 85 # documentation.
89 86 #
90 87 html_theme_options = {
91 - 'canonical_url': 'https://nncli.org/'
88 + 'nav_title': 'NextCloud Notes Command Line Interface',
89 + 'base_url': 'https://nncli.org/',
90 +
91 + # Set the color and the accent color
92 + 'color_primary': 'grey',
93 + 'color_accent': 'blue',
94 +
95 + # Set the repo location to get a badge with stats
96 + 'repo_url': 'https://git.danielmoch.com/nncli/',
97 + 'repo_name': 'Git Repository',
98 + 'repo_type': None,
99 +
100 + 'logo_icon': '&#xe261',
101 + 'master_doc': False,
102 +
103 + 'nav_links': [
104 + {'title': 'Home', 'href': 'index', 'internal': True},
105 + {'title': 'Index', 'href': 'genindex', 'internal': True},
106 + ],
107 +
108 + # Visible levels of the global TOC; -1 means unlimited
109 + 'globaltoc_depth': -1,
110 + # If False, expand all TOC entries
111 + 'globaltoc_collapse': True,
112 + # If True, show hidden TOC entries
113 + 'globaltoc_includehidden': False,
92 114 }
93 115
94 116 # Add any paths that contain custom static files (such as style sheets) here,
95 117 # relative to this directory. They are copied after the builtin static files,
96 118 # so a file named "default.css" will overwrite the builtin "default.css".
97 -html_static_path = ['.static']
119 +html_static_path = []
98 120
99 121 # Custom sidebar templates, must be a dictionary that maps document names
100 122 # to template names.
. . .
104 126 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
105 127 # 'searchbox.html']``.
106 128 #
107 -# html_sidebars = {}
129 +html_sidebars = {'**': ['globaltoc.html', 'localtoc.html', 'searchbox.html']}
108 130
109 131
110 132 # -- Options for HTMLHelp output ---------------------------------------------
. . .
137 159 # (source start file, target name, title,
138 160 # author, documentclass [howto, manual, or own class]).
139 161 latex_documents = [
140 - (master_doc, 'nncli.tex', 'nncli Documentation',
162 + (None, 'nncli.tex', 'nncli Documentation',
141 163 'Daniel Moch', 'manual'),
142 164 ]
143 165
. . .
147 169 # One entry per manual page. List of tuples
148 170 # (source start file, name, description, authors, manual section).
149 171 man_pages = [
150 - (master_doc, 'nncli', 'nncli Documentation',
151 - [author], 1)
172 + ('nncli.1', 'nncli', 'NextCloud Notes Command Line Interface',
173 + [author], 1),
174 + ('nncli-sync.1', 'nncli-sync', 'Sync a NextCloud Notes Database',
175 + [author], 1),
176 + ('nncli-list.1', 'nncli-list', 'List Notes In a NextCloud Notes Database',
177 + [author], 1),
178 + ('nncli-export.1', 'nncli-export', 'Export Notes From a NextCloud Notes Database',
179 + [author], 1),
180 + ('nncli-dump.1', 'nncli-dump', 'Print a NextCloud Note',
181 + [author], 1),
182 + ('nncli-create.1', 'nncli-create', 'Create a New NextCloud Note',
183 + [author], 1),
184 + ('nncli-import.1', 'nncli-import', 'Import Notes To a NextCloud Notes Database',
185 + [author], 1),
186 + ('nncli-edit.1', 'nncli-edit', 'Edit a NextCloud Note',
187 + [author], 1),
188 + ('nncli-delete.1', 'nncli-delete', 'Delete a NextCloud Note',
189 + [author], 1),
190 + ('nncli-favorite.1', 'nncli-favorite', 'Favorite a NextCloud Note',
191 + [author], 1),
192 + ('nncli-cat.1', 'nncli-cat', 'Operate on a NextCloud Note\'s Category',
193 + [author], 1),
194 + ('nncli.config.5', 'nncli.config', 'Configuration File For nncli(1)',
195 + [author], 5),
152 196 ]
153 197
154 198
. . .
158 202 # (source start file, target name, title, author,
159 203 # dir menu entry, description, category)
160 204 texinfo_documents = [
161 - (master_doc, 'nncli', 'nncli Documentation',
205 + (None, 'nncli', 'nncli Documentation',
162 206 author, 'nncli', 'One line description of project.',
163 207 'Miscellaneous'),
164 208 ]

docs/source/configuration.rst

1 1 .. _configuration:
2 +.. |here| replace:: :ref:`here<urwid:16-standard-foreground>`
2 3
3 4 Configuration
4 5 =============
5 6
6 -The current NextCloud Notes API does not support oauth authentication so
7 -your NextCloud Notes account password must be stored someplace
8 -accessible to nncli.
7 +.. include configuration/intro.rst
9 8
10 9 .. index:: single: configuration file
11 10
. . .
14 13 Configuration File
15 14 ------------------
16 15
17 -nncli pulls in configuration from the ``config`` file located in the
16 +nncli pulls in configuration from the *config* file located in the
18 17 standard location for your platform:
19 18
20 19 - Windows: ``%USERPROFILE%\AppData\Local\djmoch\nncli``
21 20
22 -- macOS: ``~/Library/Preferences/nncli``
21 +- macOS: ``$HOME/Library/Preferences/nncli``
23 22
24 23 - \*nix: ``$XDG_CONFIG_HOME/nncli/config`` or
25 24 ``$HOME/.config/nncli/config``
26 25
27 -The following directives are accepted within the ``config`` file:
26 +The following directives are accepted within the *config* file:
28 27
29 28 .. index:: pair: configuration file; general options
30 29
31 30 General Options
32 31 ~~~~~~~~~~~~~~~
33 32
34 -.. confval:: cfg_nn_host
35 -
36 - Sets the URL of the NextCloud instance to connect to.
37 -
38 - Required.
39 -
40 -.. confval:: cfg_nn_username
41 -
42 - The user name to log in as.
43 -
44 - Required.
45 -
46 -.. confval:: cfg_nn_password
47 -
48 - The password to use for log in.
49 -
50 - Optional. Overrides :confval:`cfg_nn_password_eval` if both are
51 - specified.
52 -
53 - .. note::
54 -
55 - For security reasons, use of the ``cfg_nn_password_eval`` option
56 - is recommended
57 -
58 -.. confval:: cfg_nn_password_eval
59 -
60 - A command to run to retrieve the password. The command should return
61 - the password on ``stdout``.
62 -
63 - Optional. Required if :confval:`cfg_nn_password` is not specified.
64 -
65 -.. confval:: cfg_db_path
66 -
67 - Specifies the path of the local notes cache.
68 -
69 - Optional. Default value:
70 -
71 - - Windows: ``%USERPROFILE%\AppData\Local\djmoch\nncli\Cache``
72 -
73 - - macOS: ``~/Library/Caches/nncli``
74 -
75 - - \*nix: ``$XDG_CACHE_HOME/nncli`` or ``$HOME/.cache/nncli``
76 -
77 -.. confval:: cfg_search_categories
78 -
79 - Set to ``yes`` to include categories in searches. Otherwise set to
80 - ``no``.
81 -
82 - Optional. Default value: ``yes``
83 -
84 -.. confval:: cfg_sort_mode
85 -
86 - Sets how notes are sorted in the console GUI. Set to ``date``
87 - to have them sorted by date (newest on top). Set to ``alpha`` to have
88 - them sorted alphabetically.
89 -
90 - Optional. Default value: ``date``
91 -
92 -.. confval:: cfg_favorite_ontop
93 -
94 - Determines whether notes marked as favorite are sorted on top.
95 -
96 - Optional. Default value: ``yes``
97 -
98 -.. confval:: cfg_tabstop
99 -
100 - Sets the width of a tabstop character.
101 -
102 - Optional. Default value: ``4``
103 -
104 -.. confval:: cfg_format_strftime
105 -
106 - Sets the format of the note timestamp (``%D``) in the note title. The
107 - format values are the specified in :py:func:`time.strftime`.
108 -
109 - Optional. Default value: ``%Y/%m/%d``
110 -
111 -.. confval:: cfg_format_note_title
112 -
113 - Sets the format of each line in the console GUI note list. Various
114 - formatting tags are supported for dynamically building the title
115 - string. Each of these formatting tags supports a width specifier
116 - (decimal) and a left justification (``-``) like that supported by
117 - printf:
118 -
119 - .. code-block:: none
120 -
121 - %F - flags (fixed 2 char width)
122 - X - needs sync
123 - * - favorited
124 - %T - category
125 - %D - date
126 - %N - title
127 -
128 - The default note title format pushes the note category to the far
129 - right of the terminal and left justifies the note title after the
130 - date and flags.
131 -
132 - Optional. Default value: ``[%D] %F %-N %T``
133 -
134 - Note that the ``%D`` date format is further defined by the strftime
135 - format specified in :confval:`cfg_format_strftime`.
136 -
137 -.. confval:: cfg_status_bar
138 -
139 - Sets whether or not the status bar is visible at the top of the
140 - console GUI.
141 -
142 - Optional. Default value: ``yes``
143 -
144 -.. confval:: cfg_editor
145 -
146 - Sets the command to run when opening a note for editing. The special
147 - values ``{fname}`` and ``{line}`` can be used to specify respectively
148 - the file name and line number to pass to the command.
149 -
150 - Optional. Default value: ``$VISUAL`` or ``$EDITOR`` if defined in the
151 - user's environment (preferring ``$VISUAL``), else ``vim {fname} +{line}``.
152 -
153 -.. confval:: cfg_pager
154 -
155 - Sets the command to run when opening a note for viewing in an
156 - external pager.
157 -
158 - Optional. Default value: ``$PAGER`` if defined in the user's
159 - environment, else ``less -c``.
160 -
161 -.. confval:: cfg_max_logs
162 -
163 - Sets the number of log events to display together in the consule GUI
164 - footer.
165 -
166 - Optional. Default value: ``5``
167 -
168 -.. confval:: cfg_log_timeout
169 -
170 - Sets the rate to poll for log events. Unit is seconds.
171 -
172 - Optional. Default value: ``5``
173 -
174 -.. confval:: cfg_log_reversed
175 -
176 - Sets whether or not the log is displayed in reverse-chronological
177 - order.
178 -
179 - Optional. Default value: ``yes``
180 -
181 -.. confval:: cfg_tempdir
182 -
183 - Sets a directory path to store temporary files in. ``nncli`` uses
184 - :func:`tempfile.mkstemp` under the hood, and the most nuanced
185 - description of how this value is used can be found in the discussion
186 - of the ``dir`` keyword argument there. Basically you should not
187 - specify this if you want to use the platform-standard temporary
188 - folder.
189 -
190 - Optional. Default value: *[blank]*
33 +.. include:: configuration/genopts.rst
191 34
192 35 .. index:: pair: configuration file; keybindings
193 36
194 37 Keybindings
195 38 ~~~~~~~~~~~
196 39
197 -Keybindings specify the behavior of the console GUI, and are never
198 -required in the ``config`` file. However, they all have default values,
199 -as outlined below. More information on specifying keybindings can be
200 -found in the :ref:`Urwid documentation <urwid:keyboard-input>`.
201 -
202 -.. confval:: kb_help
203 -
204 - Press to enter the help screen.
205 -
206 - Default value: ``h``
207 -
208 -.. confval:: kb_quit
209 -
210 - Press to exit the console GUI.
211 -
212 - Default value: ``q``
213 -
214 -.. confval:: kb_sync
215 -
216 - Press to force a full, bi-directional sync with the server.
217 -
218 - Default value: ``S``
219 -
220 -.. confval:: kb_down
221 -
222 - Press to move down one row.
223 -
224 - Default value: ``j``
225 -
226 -.. confval:: kb_up
227 -
228 - Press to move one row up.
229 -
230 - Default value: ``k``
231 -
232 -.. confval:: kb_page_down
233 -
234 - Press to move one page down.
235 -
236 - Default value: ``space``
237 -
238 -.. confval:: kb_page_up
239 -
240 - Press to move one page up.
241 -
242 - Default value: ``b``
243 -
244 -.. confval:: kb_half_page_down
245 -
246 - Press to move one half-page down.
247 -
248 - Default value: ``ctrl d``
249 -
250 -.. confval:: kb_half_page_up
251 -
252 - Press to move one half-page up.
253 -
254 - Default value: ``ctrl u``
255 -
256 -.. confval:: kb_bottom
257 -
258 - Press to move to the last line.
259 -
260 - Default value: ``G``
261 -
262 -.. confval:: kb_top
263 -
264 - Press to move to the first line.
265 -
266 - Default value: ``g``
267 -
268 -.. confval:: kb_status
269 -
270 - Press to toggle the visibility of the status bar.
271 -
272 - Default value: ``s``
273 -
274 -.. confval:: kb_create_note
275 -
276 - Press to create a new note and open in the configured editor (see
277 - :confval:`cfg_editor`).
278 -
279 - Default value: ``C``
280 -
281 -.. confval:: kb_edit_note
282 -
283 - Press to edit the highlighted note in the configured editor (see
284 - :confval:`cfg_editor`).
285 -
286 - Default value: ``e``
287 -
288 -.. confval:: kb_view_note
289 -
290 - Press to view the highlighted note in read-only mode.
291 -
292 - Default value: ``enter``
293 -
294 -.. confval:: kb_view_note_ext
295 -
296 - Press to view the highlighted note in the configured pager (see
297 - :confval:`cfg_pager`).
298 -
299 - Default value: ``meta enter``
300 -
301 -.. confval:: kb_view_note_json
302 -
303 - Press to view the raw JSON contents of the highlighted note in
304 - read-only mode.
305 -
306 - Default value: ``O``
307 -
308 -.. confval:: kb_pipe_note
309 -
310 - Press to send the contents of the highlighted note to ``stdin`` of
311 - another program. A small command window opens at the bottom of the
312 - screen to enter the desired program.
313 -
314 - Default value: ``|``
315 -
316 -.. confval:: kb_view_next_note
317 -
318 - Press to view the contents of the next note in read-only mode.
319 -
320 - Default value: ``J``
321 -
322 -.. confval:: kb_view_prev_note
323 -
324 - Press to view the contents of the previous note in read-only mode.
325 -
326 - Default value: ``K``
327 -
328 -.. confval:: kb_view_log
329 -
330 - Press to view the log.
331 -
332 - Default value: ``l``
333 -
334 -.. confval:: kb_tabstop2
335 -
336 - Press to set the tabstop for the internal pager to a width of two
337 - characters.
338 -
339 - Default value: ``2``
340 -
341 -.. confval:: kb_tabstop4
342 -
343 - Press to set the tabstop for the internal pager to a width of four
344 - characters.
345 -
346 - Default value: ``4``
347 -
348 -.. confval:: kb_tabstop8
349 -
350 - Press to set the tabstop for the internal pager to a width of eight
351 - characters.
352 -
353 - Default value: ``8``
354 -
355 -.. confval:: kb_search_gstyle
356 -
357 - Press to initiate a search of your notes against a Google-style
358 - search term. A command window will open at the bottom of the screen
359 - to enter your search term.
360 -
361 - Default value: ``/``
362 -
363 -.. confval:: kb_search_regex
364 -
365 - Press to initiate a search of your notes against a regular
366 - expression. A command window will open at the bottom of the screen to
367 - enter your search term.
368 -
369 - Default value: ``meta /``
370 -
371 -.. confval:: kb_search_prev_gstyle
372 -
373 - Press to initiate a reverse search of your notes against a
374 - Google-style search term. A command window will open at the bottom of
375 - the screen to enter your search term.
376 -
377 - Default value: ``?``
378 -
379 -.. confval:: kb_search_prev_regex
380 -
381 - Press to initiate a reverse search of your notes against a regular
382 - expression. A command window will open at the bottom of the screen
383 - to enter your search term.
384 -
385 - Default value: ``meta ?``
386 -
387 -.. confval:: kb_search_next
388 -
389 - Press after a search has been initiated to move to the next match.
390 -
391 - Default value: ``n``
392 -
393 -.. confval:: kb_search_prev
394 -
395 - Press after a search has been initiated to move to the previous
396 - match.
397 -
398 - Default value: ``N``
399 -
400 -.. confval:: kb_clear_search
401 -
402 - Press to clear the current search.
403 -
404 - Default value: ``A``
405 -
406 -.. confval:: kb_sort_date
407 -
408 - Press to display notes sorted by date.
409 -
410 - Default value: ``d``
411 -
412 -.. confval:: kb_sort_alpha
413 -
414 - Press to display notes sorted alphabetically.
415 -
416 - Default value: ``a``
417 -
418 -.. confval:: kb_sort_categories
419 -
420 - Press to display notes sorted by category.
421 -
422 - Default value: ``ctrl t``
423 -
424 -.. confval:: kb_note_delete
425 -
426 - Press to delete a note. The note will be deleted locally and
427 - reflected on the server after the next full sync (see
428 - :confval:`kb_sync`).
429 -
430 - Default value: ``D``
431 -
432 -.. confval:: kb_note_favorite
433 -
434 - Press to toggle the ``favorite`` flag for a note.
435 -
436 - Default value: ``p``
437 -
438 -.. confval:: kb_note_category
439 -
440 - Press to set/edit the note category. A command window will appear at
441 - the bottom of the screen containing the current category (if it has
442 - one). Set to an empty string to clear the category.
443 -
444 - Default value: ``t``
445 -
446 -.. confval:: kb_copy_note_text
447 -
448 - Press to copy the note text to the system clipboard.
449 -
450 - Default value: ``y``
451 40
452 41 .. index:: pair: configuration file; colors
453 42
. . .
457 46 nncli utilizes the Python Urwid_ module to implement the console user
458 47 interface.
459 48
460 -.. note::
461 -
462 - At this time, nncli does not yet support 256-color terminals and is
463 - limited to just 16-colors. Color names that can be specified in the
464 - ``config`` file are listed :ref:`here
465 - <urwid:16-standard-foreground>`.
466 -
467 -The following pairs of configuration values represent the foreground and
468 -background colors for different elements of the console GUI. In each
469 -case the configuration value corresponding to the foreground color ends
470 -in ``_fg``, and the configuration value corresponding to the
471 -background color ends in ``_bg``. The default color values are listed in
472 -foreground/background format.
49 +.. include:: configuration/colors.rst
473 50
474 51 .. _Urwid: http://urwid.org
475 52
476 -.. confval:: clr_default_fg
477 -
478 -.. confval:: clr_default_bg
479 -
480 - The default foreground/background colors.
481 -
482 - Default values: ``default/default``
483 -
484 -.. confval:: clr_status_bar_fg
485 -
486 -.. confval:: clr_status_bar_bg
487 -
488 - The foreground/background colors for the status bar.
489 -
490 - Default values: ``dark gray/light gray``
491 -
492 -.. confval:: clr_log_fg
493 -
494 -.. confval:: clr_log_bg
495 -
496 - The foreground/background colors for the log.
497 -
498 - Default values: ``dark gray/light gray``
499 -
500 -.. confval:: clr_user_input_bar_fg
501 -
502 -.. confval:: clr_user_input_bar_bg
503 -
504 - The foreground/background colors for the input bar.
505 -
506 - Default values: ``white/light red``
507 -
508 -.. confval:: clr_note_focus_fg
509 -
510 -.. confval:: clr_note_focus_bg
511 -
512 - The foreground/background colors for the selected note.
513 -
514 - Default values: ``white/light red``
515 -
516 -.. confval:: clr_note_title_day_fg
517 -
518 -.. confval:: clr_note_title_day_bg
519 -
520 - The foreground/background colors for notes edited within the past 24
521 - hours.
522 -
523 - Default values: ``light red/default``
524 -
525 -.. confval:: clr_note_title_week_fg
526 -
527 -.. confval:: clr_note_title_week_bg
528 -
529 - The foreground/background colors for notes edited within the past
530 - week,
531 -
532 - Default values: ``light green/default``
533 -
534 -.. confval:: clr_note_title_month_fg
535 -
536 -.. confval:: clr_note_title_month_bg
537 -
538 - The foreground/background colors for notes edited within the past
539 - month.
540 -
541 - Default values: ``brown/default``
542 -
543 -.. confval:: clr_note_title_year_fg
544 -
545 -.. confval:: clr_note_title_year_bg
546 -
547 - The foreground/background colors for notes edited within the past
548 - year.
549 -
550 - Default values: ``light blue/default``
551 -
552 -.. confval:: clr_note_title_ancient_fg
553 -
554 -.. confval:: clr_note_title_ancient_bg
555 -
556 - The foreground/background colors for notes last edited more than one
557 - year ago.
558 -
559 - Default values: ``light blue/default``
560 -
561 -.. confval:: clr_note_date_fg
562 -
563 -.. confval:: clr_note_date_bg
564 -
565 - The foreground/background colors for the note date (i.e. the ``%D``
566 - portion of :confval:`cfg_format_note_title`).
567 -
568 - Default values: ``dark blue/default``
569 -
570 -.. confval:: clr_note_flags_fg
571 -
572 -.. confval:: clr_note_flags_bg
573 -
574 - The foreground/background colors for the note flags (i.e., the ``%F``
575 - portion of :confval:`cfg_format_note_title`).
576 -
577 - Default values: ``dark magenta/default``
578 -
579 -.. confval:: clr_note_category_fg
580 -
581 -.. confval:: clr_note_category_bg
582 -
583 - The foreground/background colors for the note category (i.e., the
584 - ``%T`` portion of :confval:`cfg_format_note_title`).
585 -
586 - Default values: ``dark red/default``
587 -
588 -.. confval:: clr_note_content_fg
589 -
590 -.. confval:: clr_note_content_bg
591 -
592 - The foreground/background colors for the note content as displayed
593 - in the internal pager.
594 -
595 - Default values: ``default/default``
596 -
597 -.. confval:: clr_note_content_focus_fg
598 -
599 -.. confval:: clr_note_content_focus_bg
600 -
601 - The foreground/background colors for focused content within the
602 - internal pager.
603 -
604 - Default values: ``white/light red``
605 -
606 -.. confval:: clr_note_content_old_fg
607 -
608 -.. confval:: clr_note_content_old_bg
609 -
610 - The foreground/background colors for old note content as displayed
611 - within the internal pager.
612 -
613 - Default values: ``yellow/dark gray``
614 -
615 -.. confval:: clr_note_content_old_focus_fg
616 -
617 -.. confval:: clr_note_content_old_focus_bg
618 -
619 - The foreground/background colors for old note focused content as
620 - displayed within the internal pager.
621 -
622 - Default values: ``white/light red``
623 -
624 -.. confval:: clr_help_focus_fg
625 -
626 -.. confval:: clr_help_focus_bg
627 -
628 - The foreground/background colors for focused content in the help
629 - screen.
630 -
631 - Default values: ``white/light red``
632 -
633 -.. confval:: clr_help_header_fg
634 -
635 -.. confval:: clr_help_header_bg
636 -
637 - The foreground/background colors for header content in the help
638 - screen.
639 -
640 - Default values: ``dark blue/default``
641 -
642 -.. confval:: clr_help_config_fg
643 -
644 -.. confval:: clr_help_config_bg
645 -
646 - The foreground/background colors for configuration option name (e.g.,
647 - ``clr_help_focus_bg``) in the help screen.
648 -
649 - Default values: ``dark green/default``
650 -
651 -.. confval:: clr_help_value_fg
652 -
653 -.. confval:: clr_help_value_bg
654 -
655 - The foreground/background colors for the value of a configuration
656 - option as set in ``config``.
657 -
658 - Default values: ``dark red/default``
659 -
660 -.. confval:: clr_help_descr_fg
661 -
662 -.. confval:: clr_help_descr_bg
663 -
664 - The foreground/background colors for the configuration options
665 - description in the help screen.
666 -
667 - Default values: ``default/default``
668 -
669 53 Examples
670 54 --------
671 55
. . .
690 74
691 75 See example configuration file below for more notes.
692 76
693 -.. code-block:: ini
77 +::
694 78
695 79 [nncli]
696 80 cfg_nn_username = lebowski@thedude.com

docs/source/configuration/colors.rst (created)

1 +.. note::
2 +
3 + At this time, nncli does not yet support 256-color terminals and is
4 + limited to just 16-colors. Color names that can be specified in the
5 + ``config`` file are listed |here|.
6 +
7 +The following pairs of configuration values represent the foreground and
8 +background colors for different elements of the console GUI. In each
9 +case the configuration value corresponding to the foreground color ends
10 +in ``_fg``, and the configuration value corresponding to the
11 +background color ends in ``_bg``. The default color values are listed in
12 +foreground/background format.
13 +
14 +.. describe:: clr_default_fg
15 +
16 +.. describe:: clr_default_bg
17 +
18 + The default foreground/background colors.
19 +
20 + Default values: ``default/default``
21 +
22 +.. describe:: clr_status_bar_fg
23 +
24 +.. describe:: clr_status_bar_bg
25 +
26 + The foreground/background colors for the status bar.
27 +
28 + Default values: ``dark gray/light gray``
29 +
30 +.. describe:: clr_log_fg
31 +
32 +.. describe:: clr_log_bg
33 +
34 + The foreground/background colors for the log.
35 +
36 + Default values: ``dark gray/light gray``
37 +
38 +.. describe:: clr_user_input_bar_fg
39 +
40 +.. describe:: clr_user_input_bar_bg
41 +
42 + The foreground/background colors for the input bar.
43 +
44 + Default values: ``white/light red``
45 +
46 +.. describe:: clr_note_focus_fg
47 +
48 +.. describe:: clr_note_focus_bg
49 +
50 + The foreground/background colors for the selected note.
51 +
52 + Default values: ``white/light red``
53 +
54 +.. describe:: clr_note_title_day_fg
55 +
56 +.. describe:: clr_note_title_day_bg
57 +
58 + The foreground/background colors for notes edited within the past 24
59 + hours.
60 +
61 + Default values: ``light red/default``
62 +
63 +.. describe:: clr_note_title_week_fg
64 +
65 +.. describe:: clr_note_title_week_bg
66 +
67 + The foreground/background colors for notes edited within the past
68 + week,
69 +
70 + Default values: ``light green/default``
71 +
72 +.. describe:: clr_note_title_month_fg
73 +
74 +.. describe:: clr_note_title_month_bg
75 +
76 + The foreground/background colors for notes edited within the past
77 + month.
78 +
79 + Default values: ``brown/default``
80 +
81 +.. describe:: clr_note_title_year_fg
82 +
83 +.. describe:: clr_note_title_year_bg
84 +
85 + The foreground/background colors for notes edited within the past
86 + year.
87 +
88 + Default values: ``light blue/default``
89 +
90 +.. describe:: clr_note_title_ancient_fg
91 +
92 +.. describe:: clr_note_title_ancient_bg
93 +
94 + The foreground/background colors for notes last edited more than one
95 + year ago.
96 +
97 + Default values: ``light blue/default``
98 +
99 +.. describe:: clr_note_date_fg
100 +
101 +.. describe:: clr_note_date_bg
102 +
103 + The foreground/background colors for the note date (i.e. the ``%D``
104 + portion of :confval:`cfg_format_note_title`).
105 +
106 + Default values: ``dark blue/default``
107 +
108 +.. describe:: clr_note_flags_fg
109 +
110 +.. describe:: clr_note_flags_bg
111 +
112 + The foreground/background colors for the note flags (i.e., the ``%F``
113 + portion of :confval:`cfg_format_note_title`).
114 +
115 + Default values: ``dark magenta/default``
116 +
117 +.. describe:: clr_note_category_fg
118 +
119 +.. describe:: clr_note_category_bg
120 +
121 + The foreground/background colors for the note category (i.e., the
122 + ``%T`` portion of :confval:`cfg_format_note_title`).
123 +
124 + Default values: ``dark red/default``
125 +
126 +.. describe:: clr_note_content_fg
127 +
128 +.. describe:: clr_note_content_bg
129 +
130 + The foreground/background colors for the note content as displayed
131 + in the internal pager.
132 +
133 + Default values: ``default/default``
134 +
135 +.. describe:: clr_note_content_focus_fg
136 +
137 +.. describe:: clr_note_content_focus_bg
138 +
139 + The foreground/background colors for focused content within the
140 + internal pager.
141 +
142 + Default values: ``white/light red``
143 +
144 +.. describe:: clr_note_content_old_fg
145 +
146 +.. describe:: clr_note_content_old_bg
147 +
148 + The foreground/background colors for old note content as displayed
149 + within the internal pager.
150 +
151 + Default values: ``yellow/dark gray``
152 +
153 +.. describe:: clr_note_content_old_focus_fg
154 +
155 +.. describe:: clr_note_content_old_focus_bg
156 +
157 + The foreground/background colors for old note focused content as
158 + displayed within the internal pager.
159 +
160 + Default values: ``white/light red``
161 +
162 +.. describe:: clr_help_focus_fg
163 +
164 +.. describe:: clr_help_focus_bg
165 +
166 + The foreground/background colors for focused content in the help
167 + screen.
168 +
169 + Default values: ``white/light red``
170 +
171 +.. describe:: clr_help_header_fg
172 +
173 +.. describe:: clr_help_header_bg
174 +
175 + The foreground/background colors for header content in the help
176 + screen.
177 +
178 + Default values: ``dark blue/default``
179 +
180 +.. describe:: clr_help_config_fg
181 +
182 +.. describe:: clr_help_config_bg
183 +
184 + The foreground/background colors for configuration option name (e.g.,
185 + ``clr_help_focus_bg``) in the help screen.
186 +
187 + Default values: ``dark green/default``
188 +
189 +.. describe:: clr_help_value_fg
190 +
191 +.. describe:: clr_help_value_bg
192 +
193 + The foreground/background colors for the value of a configuration
194 + option as set in ``config``.
195 +
196 + Default values: ``dark red/default``
197 +
198 +.. describe:: clr_help_descr_fg
199 +
200 +.. describe:: clr_help_descr_bg
201 +
202 + The foreground/background colors for the configuration options
203 + description in the help screen.
204 +
205 + Default values: ``default/default``

docs/source/configuration/genopts.rst (created)

1 +.. describe:: cfg_nn_host
2 +
3 + Sets the URL of the NextCloud instance to connect to.
4 +
5 + Required.
6 +
7 +.. describe:: cfg_nn_username
8 +
9 + The user name to log in as.
10 +
11 + Required.
12 +
13 +.. describe:: cfg_nn_password
14 +
15 + The password to use for log in.
16 +
17 + Optional. Overrides :confval:`cfg_nn_password_eval` if both are
18 + specified.
19 +
20 + .. note::
21 +
22 + For security reasons, use of the ``cfg_nn_password_eval`` option
23 + is recommended
24 +
25 +.. describe:: cfg_nn_password_eval
26 +
27 + A command to run to retrieve the password. The command should return
28 + the password on ``stdout``.
29 +
30 + Optional. Required if :confval:`cfg_nn_password` is not specified.
31 +
32 +.. describe:: cfg_db_path
33 +
34 + Specifies the path of the local notes cache.
35 +
36 + Optional. Default value:
37 +
38 + - Windows: ``%USERPROFILE%\AppData\Local\djmoch\nncli\Cache``
39 +
40 + - macOS: ``~/Library/Caches/nncli``
41 +
42 + - \*nix: ``$XDG_CACHE_HOME/nncli`` or ``$HOME/.cache/nncli``
43 +
44 +.. describe:: cfg_search_categories
45 +
46 + Set to ``yes`` to include categories in searches. Otherwise set to
47 + ``no``.
48 +
49 + Optional. Default value: ``yes``
50 +
51 +.. describe:: cfg_sort_mode
52 +
53 + Sets how notes are sorted in the console GUI. Set to ``date``
54 + to have them sorted by date (newest on top). Set to ``alpha`` to have
55 + them sorted alphabetically.
56 +
57 + Optional. Default value: ``date``
58 +
59 +.. describe:: cfg_favorite_ontop
60 +
61 + Determines whether notes marked as favorite are sorted on top.
62 +
63 + Optional. Default value: ``yes``
64 +
65 +.. describe:: cfg_tabstop
66 +
67 + Sets the width of a tabstop character.
68 +
69 + Optional. Default value: ``4``
70 +
71 +.. describe:: cfg_format_strftime
72 +
73 + Sets the format of the note timestamp (``%D``) in the note title. The
74 + format values are the specified in :py:func:`time.strftime`.
75 +
76 + Optional. Default value: ``%Y/%m/%d``
77 +
78 +.. describe:: cfg_format_note_title
79 +
80 + Sets the format of each line in the console GUI note list. Various
81 + formatting tags are supported for dynamically building the title
82 + string. Each of these formatting tags supports a width specifier
83 + (decimal) and a left justification (``-``) like that supported by
84 + printf:
85 +
86 + .. code-block:: none
87 +
88 + %F - flags (fixed 2 char width)
89 + X - needs sync
90 + * - favorited
91 + %T - category
92 + %D - date
93 + %N - title
94 +
95 + The default note title format pushes the note category to the far
96 + right of the terminal and left justifies the note title after the
97 + date and flags.
98 +
99 + Optional. Default value: ``[%D] %F %-N %T``
100 +
101 + Note that the ``%D`` date format is further defined by the strftime
102 + format specified in :confval:`cfg_format_strftime`.
103 +
104 +.. describe:: cfg_status_bar
105 +
106 + Sets whether or not the status bar is visible at the top of the
107 + console GUI.
108 +
109 + Optional. Default value: ``yes``
110 +
111 +.. describe:: cfg_editor
112 +
113 + Sets the command to run when opening a note for editing. The special
114 + values ``{fname}`` and ``{line}`` can be used to specify respectively
115 + the file name and line number to pass to the command.
116 +
117 + Optional. Default value: ``$VISUAL`` or ``$EDITOR`` if defined in the
118 + user's environment (preferring ``$VISUAL``), else ``vim {fname} +{line}``.
119 +
120 +.. describe:: cfg_pager
121 +
122 + Sets the command to run when opening a note for viewing in an
123 + external pager.
124 +
125 + Optional. Default value: ``$PAGER`` if defined in the user's
126 + environment, else ``less -c``.
127 +
128 +.. describe:: cfg_max_logs
129 +
130 + Sets the number of log events to display together in the consule GUI
131 + footer.
132 +
133 + Optional. Default value: ``5``
134 +
135 +.. describe:: cfg_log_timeout
136 +
137 + Sets the rate to poll for log events. Unit is seconds.
138 +
139 + Optional. Default value: ``5``
140 +
141 +.. describe:: cfg_log_reversed
142 +
143 + Sets whether or not the log is displayed in reverse-chronological
144 + order.
145 +
146 + Optional. Default value: ``yes``
147 +
148 +.. describe:: cfg_tempdir
149 +
150 + Sets a directory path to store temporary files in. ``nncli`` uses
151 + :func:`tempfile.mkstemp` under the hood, and the most nuanced
152 + description of how this value is used can be found in the discussion
153 + of the ``dir`` keyword argument there. Basically you should not
154 + specify this if you want to use the platform-standard temporary
155 + folder.
156 +
157 + Optional. Default value: *[blank]*

docs/source/configuration/intro.rst (created)

1 +The current NextCloud Notes API does not support OAuth authentication so
2 +your NextCloud Notes account password must be stored someplace
3 +accessible to :program:`nncli`.

docs/source/configuration/keybindings.rst (created)

1 +Keybindings specify the behavior of the console GUI, and are never
2 +required in the ``config`` file. However, they all have default values,
3 +as outlined below. More information on specifying keybindings can be
4 +found in the :ref:`Urwid documentation <urwid:keyboard-input>`.
5 +
6 +.. describe:: kb_help
7 +
8 + Press to enter the help screen.
9 +
10 + Default value: ``h``
11 +
12 +.. describe:: kb_quit
13 +
14 + Press to exit the console GUI.
15 +
16 + Default value: ``q``
17 +
18 +.. describe:: kb_sync
19 +
20 + Press to force a full, bi-directional sync with the server.
21 +
22 + Default value: ``S``
23 +
24 +.. describe:: kb_down
25 +
26 + Press to move down one row.
27 +
28 + Default value: ``j``
29 +
30 +.. describe:: kb_up
31 +
32 + Press to move one row up.
33 +
34 + Default value: ``k``
35 +
36 +.. describe:: kb_page_down
37 +
38 + Press to move one page down.
39 +
40 + Default value: ``space``
41 +
42 +.. describe:: kb_page_up
43 +
44 + Press to move one page up.
45 +
46 + Default value: ``b``
47 +
48 +.. describe:: kb_half_page_down
49 +
50 + Press to move one half-page down.
51 +
52 + Default value: ``ctrl d``
53 +
54 +.. describe:: kb_half_page_up
55 +
56 + Press to move one half-page up.
57 +
58 + Default value: ``ctrl u``
59 +
60 +.. describe:: kb_bottom
61 +
62 + Press to move to the last line.
63 +
64 + Default value: ``G``
65 +
66 +.. describe:: kb_top
67 +
68 + Press to move to the first line.
69 +
70 + Default value: ``g``
71 +
72 +.. describe:: kb_status
73 +
74 + Press to toggle the visibility of the status bar.
75 +
76 + Default value: ``s``
77 +
78 +.. describe:: kb_create_note
79 +
80 + Press to create a new note and open in the configured editor (see
81 + :confval:`cfg_editor`).
82 +
83 + Default value: ``C``
84 +
85 +.. describe:: kb_edit_note
86 +
87 + Press to edit the highlighted note in the configured editor (see
88 + :confval:`cfg_editor`).
89 +
90 + Default value: ``e``
91 +
92 +.. describe:: kb_view_note
93 +
94 + Press to view the highlighted note in read-only mode.
95 +
96 + Default value: ``enter``
97 +
98 +.. describe:: kb_view_note_ext
99 +
100 + Press to view the highlighted note in the configured pager (see
101 + :confval:`cfg_pager`).
102 +
103 + Default value: ``meta enter``
104 +
105 +.. describe:: kb_view_note_json
106 +
107 + Press to view the raw JSON contents of the highlighted note in
108 + read-only mode.
109 +
110 + Default value: ``O``
111 +
112 +.. describe:: kb_pipe_note
113 +
114 + Press to send the contents of the highlighted note to ``stdin`` of
115 + another program. A small command window opens at the bottom of the
116 + screen to enter the desired program.
117 +
118 + Default value: ``|``
119 +
120 +.. describe:: kb_view_next_note
121 +
122 + Press to view the contents of the next note in read-only mode.
123 +
124 + Default value: ``J``
125 +
126 +.. describe:: kb_view_prev_note
127 +
128 + Press to view the contents of the previous note in read-only mode.
129 +
130 + Default value: ``K``
131 +
132 +.. describe:: kb_view_log
133 +
134 + Press to view the log.
135 +
136 + Default value: ``l``
137 +
138 +.. describe:: kb_tabstop2
139 +
140 + Press to set the tabstop for the internal pager to a width of two
141 + characters.
142 +
143 + Default value: ``2``
144 +
145 +.. describe:: kb_tabstop4
146 +
147 + Press to set the tabstop for the internal pager to a width of four
148 + characters.
149 +
150 + Default value: ``4``
151 +
152 +.. describe:: kb_tabstop8
153 +
154 + Press to set the tabstop for the internal pager to a width of eight
155 + characters.
156 +
157 + Default value: ``8``
158 +
159 +.. describe:: kb_search_gstyle
160 +
161 + Press to initiate a search of your notes against a Google-style
162 + search term. A command window will open at the bottom of the screen
163 + to enter your search term.
164 +
165 + Default value: ``/``
166 +
167 +.. describe:: kb_search_regex
168 +
169 + Press to initiate a search of your notes against a regular
170 + expression. A command window will open at the bottom of the screen to
171 + enter your search term.
172 +
173 + Default value: ``meta /``
174 +
175 +.. describe:: kb_search_prev_gstyle
176 +
177 + Press to initiate a reverse search of your notes against a
178 + Google-style search term. A command window will open at the bottom of
179 + the screen to enter your search term.
180 +
181 + Default value: ``?``
182 +
183 +.. describe:: kb_search_prev_regex
184 +
185 + Press to initiate a reverse search of your notes against a regular
186 + expression. A command window will open at the bottom of the screen
187 + to enter your search term.
188 +
189 + Default value: ``meta ?``
190 +
191 +.. describe:: kb_search_next
192 +
193 + Press after a search has been initiated to move to the next match.
194 +
195 + Default value: ``n``
196 +
197 +.. describe:: kb_search_prev
198 +
199 + Press after a search has been initiated to move to the previous
200 + match.
201 +
202 + Default value: ``N``
203 +
204 +.. describe:: kb_clear_search
205 +
206 + Press to clear the current search.
207 +
208 + Default value: ``A``
209 +
210 +.. describe:: kb_sort_date
211 +
212 + Press to display notes sorted by date.
213 +
214 + Default value: ``d``
215 +
216 +.. describe:: kb_sort_alpha
217 +
218 + Press to display notes sorted alphabetically.
219 +
220 + Default value: ``a``
221 +
222 +.. describe:: kb_sort_categories
223 +
224 + Press to display notes sorted by category.
225 +
226 + Default value: ``ctrl t``
227 +
228 +.. describe:: kb_note_delete
229 +
230 + Press to delete a note. The note will be deleted locally and
231 + reflected on the server after the next full sync (see
232 + :confval:`kb_sync`).
233 +
234 + Default value: ``D``
235 +
236 +.. describe:: kb_note_favorite
237 +
238 + Press to toggle the ``favorite`` flag for a note.
239 +
240 + Default value: ``p``
241 +
242 +.. describe:: kb_note_category
243 +
244 + Press to set/edit the note category. A command window will appear at
245 + the bottom of the screen containing the current category (if it has
246 + one). Set to an empty string to clear the category.
247 +
248 + Default value: ``t``
249 +
250 +.. describe:: kb_copy_note_text
251 +
252 + Press to copy the note text to the system clipboard.
253 +
254 + Default value: ``y``

docs/source/contributing.rst (created)

1 +.. _contribution guide:
2 +
3 +.. include:: ../../CONTRIBUTING.rst

docs/source/index.rst

11 11 .. image:: https://img.shields.io/pypi/l/nncli.svg
12 12 :alt: PyPI - License
13 13 :target: https://git.danielmoch.com/nncli/tree/LICENSE
14 - .. image:: https://builds.danielmoch.com/badges/nncli.svg
15 - :alt: Daniel Moch CI
16 - :target: https://builds.danielmoch.com/#/builders/nncli
17 14 .. image:: https://img.shields.io/pypi/v/nncli.svg
18 15 :alt: PyPI
19 16 :target: https://pypi.org/project/nncli
20 17
21 18 .. include:: ../../README.rst
22 19
23 -Contents
24 ---------
20 +Documentation Contents
21 +----------------------
25 22
26 23 .. toctree::
27 24 :maxdepth: 2
28 25
29 26 configuration
30 27 usage
28 + contributing
29 + changelog
31 30
31 +.. toctree::
32 + :caption: Manuals
33 + :titlesonly:
32 34
33 -Indices and tables
34 -------------------
35 + nncli.1
36 + nncli-sync.1
37 + nncli-list.1
38 + nncli-export.1
39 + nncli-dump.1
40 + nncli-create.1
41 + nncli-import.1
42 + nncli-edit.1
43 + nncli-delete.1
44 + nncli-favorite.1
45 + nncli-cat.1
46 + nncli.config.5
35 47
36 -* :ref:`genindex`
37 -* :ref:`search`
48 +
49 +Index
50 +-----
51 +
52 +:ref:`genindex`

docs/source/nncli-cat.1.rst (created)

1 +nncli-cat(1)
2 +============
3 +
4 +Synopsis
5 +--------
6 +
7 +:program:`nncli` *--key|-k KEY cat get|set|rm* [*category_name*]
8 +
9 +Description
10 +-----------
11 +
12 +.. include:: usage/cat-desc.rst
13 +
14 +Options
15 +-------
16 +
17 +.. include:: usage/cat-args.rst
18 +
19 +Examples
20 +--------
21 +
22 +.. include:: usage/cat-example.rst
23 +
24 +See also
25 +--------
26 +
27 +:manpage:`nncli(1)`

docs/source/nncli-create.1.rst (created)

1 +nncli-create(1)
2 +===============
3 +
4 +Synopsis
5 +--------
6 +
7 +**nncli create** [-]
8 +
9 +Description
10 +-----------
11 +
12 +.. include:: usage/create-desc.rst
13 +
14 +Examples
15 +--------
16 +
17 +.. include:: usage/create-example.rst
18 +
19 +See also
20 +--------
21 +
22 +:manpage:`nncli(1)`

docs/source/nncli-delete.1.rst (created)

1 +nncli-delete(1)
2 +===============
3 +
4 +Synopsis
5 +--------
6 +
7 +:program:`nncli` *--key|-k KEY delete*
8 +
9 +Description
10 +-----------
11 +
12 +.. include:: usage/delete-desc.rst
13 +
14 +Options
15 +-------
16 +
17 +.. include:: usage/delete-args.rst
18 +
19 +See also
20 +--------
21 +
22 +:manpage:`nncli(1)`

docs/source/nncli-dump.1.rst (created)

1 +nncli-dump(1)
2 +=============
3 +
4 +Synopsis
5 +--------
6 +
7 +**nncli dump** [*options*] [*search_string*]
8 +
9 +Description
10 +-----------
11 +
12 +.. include:: usage/dump-desc.rst
13 +
14 +Options
15 +-------
16 +
17 +.. include:: usage/dump-args.rst
18 +
19 +See also
20 +--------
21 +
22 +:manpage:`nncli(1)`

docs/source/nncli-edit.1.rst (created)

1 +nncli-edit(1)
2 +=============
3 +
4 +Synopsis
5 +--------
6 +
7 +:program:`nncli` *--key|-k KEY edit*
8 +
9 +Description
10 +-----------
11 +
12 +.. include:: usage/edit-desc.rst
13 +
14 +Options
15 +-------
16 +
17 +.. include:: usage/edit-args.rst
18 +
19 +See also
20 +--------
21 +
22 +:manpage:`nncli(1)`

docs/source/nncli-export.1.rst (created)

1 +nncli-export(1)
2 +===============
3 +
4 +Synopsis
5 +--------
6 +
7 +**nncli export** [*options*] [*search_string*]
8 +
9 +Description
10 +-----------
11 +
12 +.. include:: usage/export-desc.rst
13 +
14 +Options
15 +-------
16 +
17 +.. include:: usage/export-args.rst
18 +
19 +Examples
20 +--------
21 +
22 +.. include:: usage/export-example.rst
23 +
24 +See also
25 +--------
26 +
27 +:manpage:`nncli(1)`

docs/source/nncli-favorite.1.rst (created)

1 +nncli-favorite(1)
2 +=================
3 +
4 +Synopsis
5 +--------
6 +
7 +:program:`nncli` *--key|-k KEY favorite|unfavorite*
8 +
9 +Description
10 +-----------
11 +
12 +.. include:: usage/favorite-desc.rst
13 +
14 +Options
15 +-------
16 +
17 +.. include:: usage/favorite-args.rst
18 +
19 +See also
20 +--------
21 +
22 +:manpage:`nncli(1)`

docs/source/nncli-import.1.rst (created)

1 +nncli-import(1)
2 +===============
3 +
4 +Synopsis
5 +--------
6 +
7 +**nncli import** [-]
8 +
9 +Description
10 +-----------
11 +
12 +.. include:: usage/import-desc.rst
13 +
14 +Examples
15 +--------
16 +
17 +.. include:: usage/import-example.rst
18 +
19 +See also
20 +--------
21 +
22 +:manpage:`nncli(1)`

docs/source/nncli-list.1.rst (created)

1 +nncli-list(1)
2 +=============
3 +
4 +Synopsis
5 +--------
6 +
7 +**nncli list** [*options*] [*search_string*]
8 +
9 +Description
10 +-----------
11 +
12 +.. include:: usage/list-desc.rst
13 +
14 +Options
15 +-------
16 +
17 +.. include:: usage/list-args.rst
18 +
19 +See also
20 +--------
21 +
22 +:manpage:`nncli(1)`

docs/source/nncli-sync.1.rst (created)

1 +nncli-sync(1)
2 +=============
3 +
4 +Synopsis
5 +--------
6 +
7 +**nncli sync**
8 +
9 +Description
10 +-----------
11 +
12 +.. include:: usage/sync-desc.rst
13 +
14 +See also
15 +--------
16 +
17 +:manpage:`nncli(1)`

docs/source/nncli.1.rst

1 -nncli - NextCloud Notes Command Line Interface
2 -==============================================
1 +nncli(1)
2 +========
3 3
4 4 Synopsis
5 5 --------
6 6
7 -**nncli** [*options*] *command* [*args*]...
7 +**nncli** [*options*] *subcommand* [*subcommand-options*] [*args*]...
8 8
9 9 Description
10 10 -----------
. . .
21 21 Options
22 22 -------
23 23
24 -.. include:: usage.rst
24 +.. include:: usage/genopts.rst
25 +.. include:: usage/subopts.rst
26 +
27 +Subcommands
28 +-----------
29 +
30 +:program:`nncli` provides the following subcommands:
31 +
32 +- :manpage:`nncli-sync(1)`
33 +- :manpage:`nncli-list(1)`
34 +- :manpage:`nncli-export(1)`
35 +- :manpage:`nncli-dump(1)`
36 +- :manpage:`nncli-create(1)`
37 +- :manpage:`nncli-import(1)`
38 +- :manpage:`nncli-edit(1)`
39 +- :manpage:`nncli-delete(1)`
40 +- :manpage:`nncli-favorite(1)`
41 +- :manpage:`nncli-cat(1)`
42 +
25 43
26 44 Environment Variables
27 45 ---------------------
28 46
47 +.. describe:: VISUAL
48 +
49 + Used to determine which program to open when editing a note.
50 +
51 +.. describe:: EDITOR
52 +
53 + Used when VISUAL is not defined to determine which program to open
54 + when editing a note. If neither is defined, :manpage:`vim(1)` is
55 + used.
56 +
57 +.. describe:: PAGER
58 +
59 + Used to specify the program used to open notes for reading. If not
60 + defined, the default is **less -c**.
61 +
62 +.. describe:: XDG_CACHE_HOME
63 +
64 + Used to determine the location of the local notes database. If not
65 + specified, *$HOME/.cache* will be used.
66 +
67 +.. describe:: XDG_CONFIG_HOME
68 +
69 + Used to determine the location of the configuration file. If not
70 + specified, *$HOME/.config* will be used.
71 +
72 +
29 73 See also
30 74 --------
31 75
76 +:manpage:`less(1)`,
32 77 :manpage:`nncli.config(5)`

docs/source/nncli.config.5.rst (created)

1 +nncli.config(5)
2 +===============
3 +
4 +.. include:: configuration/intro.rst
5 +.. |here| replace:: in the Urwid manual
6 +
7 +Configuration File
8 +------------------
9 +
10 +nncli pulls in configuration from the *config* file located in the
11 +standard location for your platform:
12 +
13 +.. describe:: macOS
14 +
15 + $HOME/Library/Preferences/nncli
16 +
17 +.. describe:: Linux/BSD
18 +
19 + $XDG_CONFIG_HOME/nncli/config or $HOME/.config/nncli/config
20 +
21 +The following directives are accepted within the *config* file:
22 +
23 +General Options
24 +~~~~~~~~~~~~~~~
25 +
26 +.. include:: configuration/genopts.rst
27 +
28 +Keybindings
29 +~~~~~~~~~~~
30 +
31 +.. include:: configuration/keybindings.rst
32 +
33 +Colors
34 +~~~~~~
35 +
36 +.. include:: configuration/colors.rst
37 +
38 +Examples
39 +--------
40 +
41 +At the very least, the following example *config* will get you going
42 +(using your account information):
43 +
44 +::
45 +
46 + [nncli]
47 + cfg_nn_username = lebowski@thedude.com
48 + cfg_nn_password = nihilist
49 + cfg_nn_host = nextcloud.thedude.com
50 +
51 +See Also
52 +--------
53 +
54 +:manpage:`nncli(1)`
55 +
56 +The Urwid Manual, Display Attributes, 16 Standard Foreground Colors

docs/source/usage.rst

1 1 Usage
2 2 =====
3 3
4 -.. program:: nncli
5 -
6 -When ``nncli`` is run without any options or arguments an interactive
7 -console GUI will appear. The behavior of this interface is highly
8 -configurable (see: :ref:`configuration`).
9 -
10 -In addition to this default behavior, there are several options
11 -available when calling ``nncli`` without a subcommand.
12 -
13 -.. option:: --help, -h
14 -
15 -Displays a brief decription of the ``nncli`` options and subcommands.
16 -
17 -.. option:: --version, -V
18 -
19 -Displays the version information.
20 -
21 -Also available when calling ``nncli`` by itself is the ``--config``
22 -option, for which see: :ref:`general-options`.
4 +.. include:: usage/genopts.rst
23 5
24 6 Subcommands
25 7 -----------
. . .
51 33 These subcommands and the options available to them are described below.
52 34
53 35 .. _general-options:
54 -
55 -General Subcommand Options
56 -~~~~~~~~~~~~~~~~~~~~~~~~~~
57 -
58 -Several ``nncli`` options apply to multiple subcommands. They are:
59 -
60 -.. option:: --verbose, -v
61 -
62 -Print verbose logging information to ``stdout``
63 -
64 -.. option:: --nosync, -n
65 -
66 -Operate only on the local notes cache. Do not reach out to the server.
67 -
68 -.. option:: --regex, -r
69 -
70 -For subcommands that accept a search string, treat the search string as
71 -a regular expression.
72 -
73 -.. option:: --key, -k
74 -
75 -The ID of the note to operate on. This option is required for many of
76 -the subcommands.
77 -
78 -.. option:: --config, -c
79 -
80 -Specify the config file to read from. This option is only required to
81 -override the default location (see: :ref:`config-file`).
36 +.. include:: usage/genopts.rst
37 +.. include:: usage/subopts.rst
82 38
83 39 nncli sync
84 40 ~~~~~~~~~~
. . .
87 43
88 44 Command format: ``nncli sync``
89 45
90 -Performs a full, bi-directional sync between the local notes cache and
91 -the NextCloud Notes server. There are no available options for this
92 -subcommand.
93 -
94 -- Available options: None
95 -
96 -- Arguments: None
46 +.. include:: usage/sync-desc.rst
97 47
98 48 nncli list
99 49 ~~~~~~~~~~
100 50
101 51 .. program:: nncli list
102 52
103 -Command format: ``nncli list [search_string]``
104 -
105 -List notes by ID, flags, and title. Flags indicate whether the note has
106 -been modified locally (``X``), and/or if it is marked as a favorite
107 -(``*``).
53 +Command format: :program:`nncli list` [*options*] [*search_string*]
108 54
109 -- Available options:
55 +.. include:: usage/list-desc.rst
110 56
111 - - ``--regex, -r`` See :ref:`general-options`
112 -
113 -- Arguments:
57 +Options are as follows:
114 58
115 - - ``search_string`` Optional. A search term used to refine the search.
59 +.. include:: usage/list-args.rst
116 60
117 61 nncli export
118 62 ~~~~~~~~~~~~
119 63
120 64 .. program:: nncli export
121 65
122 -Command format: ``nncli export [search_string]``
66 +Command format: :program:`nncli export` [*options*] [*search_string*]
123 67
124 -Exports notes in raw, JSON format. The JSON format is a superset of the
125 -format outlined in the NextCloud Notes API specification with
126 -information added for managing the local notes cache. Note that nncli
127 -still stores all the notes data in the directory specified by
128 -``cfg_db_path``, so for easy backups, it may be easier/quicker to simply
129 -backup this entire directory.
68 +.. include:: usage/export-desc.rst
130 69
131 -- Available options:
70 +Options are as follows:
132 71
133 - - :ref:`general-options`
134 -
135 - - ``--regex, -r`` Mutually exclusive with ``--key``
136 -
137 - - ``--key, -k``
138 -
139 -- Arguments:
140 -
141 - - ``search_string`` Required if ``--regex`` is specified. A search
142 - term used to refine the search.
72 +.. include:: usage/export-args.rst
143 73
144 74 Example:
145 75
146 -.. code-block:: sh
147 -
148 - # export a single note by id
149 - nncli -k somekeyid export
150 -
151 - # export all notes
152 - nncli export
153 -
154 - # export notes matching search string
155 - nncli [-r] export some search keywords or regex
76 +.. include:: usage/export-example.rst
156 77
157 78 nncli dump
158 79 ~~~~~~~~~~
159 80
160 81 .. program:: nncli dump
161 82
162 -Command format: ``nncli dump [search_string]``
163 -
164 -Prints notes to ``stdout``. The printed format is the text of the note
165 -preceeded by a header displaying information about the note title, key,
166 -modified date, category, and flags. Flags indicate whether the note has
167 -been modified locally (``X``), and/or if it is marked as a favorite
168 -(``*``).
169 -
170 -- Available options:
171 -
172 - - :ref:`general-options`
173 -
174 - - ``--regex, -r`` Mutually exclusive with ``--key``
83 +Command format: :program:`nncli dump` [search_string]``
175 84
176 - - ``--key, -k``
85 +.. include:: usage/dump-desc.rst
177 86
178 -- Arguments:
87 +Options are as follows:
179 88
180 - - ``search_string`` Required if ``--regex`` is specified. A search
181 - term used to refine the search.
89 +.. include:: usage/dump-args.rst
182 90
183 91 nncli create
184 92 ~~~~~~~~~~~~
185 93
186 94 .. program:: nncli create
187 95
188 -Command format: ``nncli create [-]``
189 -
190 -Create a note. Without arguments, this command will open your configured
191 -editor. The note syncs to the server after the editor is closed.
192 -
193 -- Available options: None
96 +Command format: program:`nncli create` [*-*]
194 97
195 -- Arguments:
196 -
197 - - `-` Optional. If specified, the note content is read from ``stdin``.
98 +.. include: usage/create-desc.rst
198 99
199 100 Example:
200 101
201 -.. code-block:: sh
202 -
203 - # create a new note and open in editor
204 - nncli create
205 -
206 - # create a new note with contents of stdin
207 - echo 'hi' | nncli create -
102 +.. include:: usage/create-example.rst
208 103
209 104 nncli import
210 105 ~~~~~~~~~~~~
. . .
213 108
214 109 Command format: ``nncli import [-]``
215 110
216 -Import a JSON-formatted note. nncli can import notes from raw json data
217 -(via stdin or editor). Allowed fields are ``content``, ``category``,
218 -``favorite``, and ``modified``.
219 -
220 -- Available options: None
221 -
222 -- Arguments:
223 -
224 - - ``-`` Optional. If specified, the note content is read from ``stdin``.
111 +.. include:: usage/import-desc.rst
225 112
226 113 Example:
227 114
228 -.. code-block:: none
229 -
230 - echo '{"category":"testing","content":"New note!"}' | nncli import -
115 +.. include:: usage/import-example.rst
231 116
232 117 nncli edit
233 118 ~~~~~~~~~~
234 119
235 120 .. program:: nncli edit
236 121
237 -Command format: ``nncli -k <key> edit``
238 -
239 -Open the note specified by ``<key>`` in the configured editor. The note
240 -syncs to the server after the editor is saved and closed.
122 +Command format: :program:`nncli` [*--key|-k*] *KEY edit*
241 123
242 -- Available options:
124 +.. include:: usage/edit-desc.rst
243 125
244 - - ``--key, -k`` Required. See :ref:`general-options`
126 +Options are as follows:
245 127
246 -- Arguments: None
128 +.. include:: usage/edit-args.rst
247 129
248 130 nncli delete
249 131 ~~~~~~~~~~~~
250 132
251 133 .. program:: nncli delete
252 134
253 -Command format: ``nncli -k <key> delete``
254 -
255 -Delete the note specified by ``<key>``.
135 +Command format: :program:`nncli` [*--key|-k*] *KEY delete*
256 136
257 -- Available options:
137 +.. include:: usage/delete-desc.rst
258 138
259 - - ``--key, -k`` Required. See :ref:`general-options`
139 +Options are as follows:
260 140
261 -- Arguments: None
141 +.. include:: usage/delete-args.rst
262 142
263 143 nncli favorite
264 144 ~~~~~~~~~~~~~~
265 145
266 146 .. program:: nncli favorite
267 147
268 -Command format: ``nncli -k <key> favorite|unfavorite``
269 -
270 -Favorite (or unfavorite) the note specified by ``<key>``.
148 +Command format: :program:`nncli` *--key|-k KEY favorite|unfavorite*
271 149
272 -- Available options:
150 +.. include:: usage/favorite-desc.rst
273 151
274 - - ``--key, -k`` Required. See :ref:`general-options`
152 +Options are as follows:
275 153
276 -- Arguments: None
154 +.. include:: usage/favorite-args.rst
277 155
278 156 nncli cat
279 157 ~~~~~~~~~
280 158
281 159 .. program:: nncli cat
282 160
283 -Command format: ``nncli -k <key> cat get|set|rm``
161 +Command format: :program:`nncli` *--key|-k KEY cat get|set|rm* [*category_name*]
284 162
285 -Read or modify a note category from the command line.
286 -
287 -- Available options:
288 -
289 - - ``--key, -k`` Required. See :ref:`general-options`
290 -
291 -- Arguments:
163 +.. include:: usage/cat-desc.rst
292 164
293 - - ``get`` Get the note category
165 +Options are as follows:
294 166
295 - - ``set`` Set the note category
296 -
297 - - ``rm`` Remove the note category
167 +.. include:: usage/cat-args.rst
298 168
299 169 Example:
300 170
301 -.. code-block:: sh
302 -
303 - # Retrieve note category (e.g. "category1")
304 - nncli -k somekeyid cat get
305 - # Returns "category1"
306 -
307 - # Add a category to a note, overwriting any existing one
308 - nncli -k somekeyid cat set "category3"
309 - # Now tagged as "category3"
310 -
311 - # Remove a category from a note
312 - nncli -k somekeyid cat rm
313 - # Note now has no category
171 +.. include:: usage/cat-example.rst
314 172
315 173 Console GUI Usage
316 174 -----------------

docs/source/usage/cat-args.rst (created)

1 +.. option:: --key, -k
2 +
3 + The ID of the note to operate on.

docs/source/usage/cat-desc.rst (created)

1 +Modify a note category from the command line. With the *get* argument,
2 +the command returns the note category. With the *set* argument, the
3 +note category is set to the required *category_name* argument. With
4 +the *rm* argument, the note's category is removed.

docs/source/usage/cat-example.rst (created)

1 +::
2 +
3 + # Retrieve note category (e.g. "category1")
4 + $ nncli -k 42 cat get
5 + category1
6 +
7 + # Add a category to a note, overwriting any existing one
8 + nncli -k 42 cat set "category3"
9 +
10 + # Remove a category from a note
11 + nncli -k 42 cat rm

docs/source/usage/create-desc.rst (created)

1 +Create a note. Without arguments, this command will open your
2 +configured editor. If *-* is specified, the note content is read from
3 +*stdin*. The note syncs to the server after the command completes.

docs/source/usage/create-example.rst (created)

1 +::
2 +
3 + # create a new note and open in editor
4 + $ nncli create
5 +
6 + # create a new note with contents of stdin
7 + $ echo 'hi' | nncli create -

docs/source/usage/delete-args.rst (created)

1 +.. option:: --key, -k
2 +
3 + The ID of the note to operate on.

docs/source/usage/delete-desc.rst (created)

1 +Delete the note specified by *KEY*.

docs/source/usage/dump-args.rst (created)

1 +.. option:: --regex, -r
2 +
3 + Treat *search_string* as a regular expression. Mutually exclusive
4 + with *--key*.
5 +
6 +.. option:: --key, -k
7 +
8 + The ID of the note to operate on.

docs/source/usage/dump-desc.rst (created)

1 +:program:`nncli dump` dumps notes to *stdout*. The printed format is
2 +the text of the note preceeded by a header displaying information
3 +about the note title, key, modified date, category, and flags. Flags
4 +indicate whether the note has been modified locally (*X*), and/or if
5 +it is marked as a favorite (*\**). If *search_string* is specified, it
6 +is used to filter the notes prior to export.

docs/source/usage/edit-args.rst (created)

1 +.. option:: --key, -k
2 +
3 + The ID of the note to operate on.

docs/source/usage/edit-desc.rst (created)

1 +Open the note specified by *KEY* in the configured editor. The note
2 +syncs to the server after the editor is saved and closed.

docs/source/usage/export-args.rst (created)

1 +.. option:: --regex, -r
2 +
3 + Treat *search_string* as a regular expression. Mutually exclusive
4 + with *--key*.
5 +
6 +.. option:: --key, -k
7 +
8 + The ID of the note to operate on.

docs/source/usage/export-desc.rst (created)

1 +:program:`nncli export` exports notes in raw, JSON format. The JSON
2 +format is a superset of the format outlined in the NextCloud Notes API
3 +specification with information added for managing the local notes
4 +cache. If *search_string* is specified, it is used to filter the notes
5 +prior to export.
6 +
7 +.. note::
8 +
9 + :program:`nncli` already stores all notes locally in the cache
10 + directory, so for easy backups, it may be easier/quicker to simply
11 + backup this entire directory.

docs/source/usage/export-example.rst (created)

1 +::
2 +
3 + # export a single note by id
4 + $ nncli -k somekeyid export
5 +
6 + # export all notes
7 + $ nncli export
8 +
9 + # export notes matching search string
10 + $ nncli [-r] export "some search keywords or regex"

docs/source/usage/favorite-args.rst (created)

1 +.. option:: --key, -k
2 +
3 + The ID of the note to operate on.

docs/source/usage/favorite-desc.rst (created)

1 +Favorite (or unfavorite) the note specified by *KEY*.

docs/source/usage/genopts.rst (created)

1 +General Subcommand Options
2 +~~~~~~~~~~~~~~~~~~~~~~~~~~
3 +
4 +.. program:: nncli
5 +
6 +When ``nncli`` is run without any options or arguments an interactive
7 +console GUI will appear. The appearance and behavior of the GUI may be
8 +customized through a configuration file, described elsewhere.
9 +
10 +In addition to this default behavior, there are several options
11 +available when calling ``nncli`` without a subcommand.
12 +
13 +.. option:: --help, -h
14 +
15 +Displays a brief decription of the ``nncli`` options and subcommands.
16 +
17 +.. option:: --version, -V
18 +
19 +Displays the version information.
20 +
21 +.. option:: --config, -c
22 +
23 +Specify the config file to read from. This option is only required to
24 +override the default location.

docs/source/usage/import-desc.rst (created)

1 +Import a JSON-formatted note. nncli can import notes from raw json
2 +data (via stdin or editor). Allowed fields are *content*, *category*,
3 +*favorite*, and *modified*. If *-* is specified, the note content is
4 +read from *stdin*. The note syncs to the server after the command
5 +completes.

docs/source/usage/import-example.rst (created)

1 +::
2 +
3 + $ echo '{"category":"testing","content":"New note!"}' \
4 + | nncli import -

docs/source/usage/list-args.rst (created)

1 +.. option:: --regex, -r
2 +
3 +For subcommands that accept a search string, treat the search string as
4 +a regular expression.

docs/source/usage/list-desc.rst (created)

1 +:program:`nncli list` lists notes by ID, flags, and title. Flags
2 +indicate whether the note has been modified locally (``X``), and/or if
3 +it is marked as a favorite (``*``). If *search_string* is provided, it
4 +is used to filter the list of notes.

docs/source/usage/subopts.rst (created)

1 +Common Subcommand Options
2 +~~~~~~~~~~~~~~~~~~~~~~~~~
3 +
4 +In addition to the global options, several ``nncli`` options apply to
5 +multiple subcommands. They are:
6 +
7 +.. option:: --verbose, -v
8 +
9 +Print verbose logging information to ``stdout``
10 +
11 +.. option:: --nosync, -n
12 +
13 +Operate only on the local notes cache. Do not reach out to the server.
14 +
15 +.. option:: --regex, -r
16 +
17 +For subcommands that accept a search string, treat the search string as
18 +a regular expression.
19 +
20 +.. option:: --key, -k
21 +
22 +The ID of the note to operate on. This option is required for many of
23 +the subcommands.

docs/source/usage/sync-desc.rst (created)

1 +:program:`nncli sync` performs a full, bi-directional sync between the
2 +local notes cache and the NextCloud Notes server. The command accepts
3 +no options or arguments.

nncli/__init__.py --> src/nncli/__init__.py

1 1 # -*- coding: utf-8 -*-
2 2 """NextCloud Notes Command Line Interface"""
3 3
4 -__version__ = '0.3.5'
4 +__version__ = '0.3.6'

nncli/__main__.py --> src/nncli/__main__.py