From 8453c268f55ef7cfbc2fe6a6bc5c8ca7a67c8880 Mon Sep 17 00:00:00 2001
From: Elena ``of Valhalla'' Grandi <valhalla@trueelena.org>
Date: Thu, 1 Oct 2020 23:04:58 +0200
Subject: Moved misc docs to sphinx

---
 docs/source/getting_started_command_line.rst    | 62 +++++++++++++++++++++++++
 docs/source/index.rst                           |  4 ++
 docs/source/moving_data_between_collections.rst | 41 ++++++++++++++++
 docs/source/promises.rst                        | 36 ++++++++++++++
 4 files changed, 143 insertions(+)
 create mode 100644 docs/source/getting_started_command_line.rst
 create mode 100644 docs/source/moving_data_between_collections.rst
 create mode 100644 docs/source/promises.rst

(limited to 'docs/source')

diff --git a/docs/source/getting_started_command_line.rst b/docs/source/getting_started_command_line.rst
new file mode 100644
index 0000000..0c4d507
--- /dev/null
+++ b/docs/source/getting_started_command_line.rst
@@ -0,0 +1,62 @@
+******************************
+Getting Started (Command Line)
+******************************
+
+lesana can be used from the command line through the ``lesana`` command;
+for more details run ``lesana help``.
+
+Many commands will try to open some file in an editor: they will attempt
+to use, in this order, ``$EDITOR``, ``sensible-editor`` or as a fallback
+``vi``, which should be installed on any POSIX-like system.
+
+To start a new collection, create a directory and run ``lesana
+init`` into it::
+
+    mkdir $DIRECTORY
+    cd $DIRECTORY
+    lesana init
+
+It will create the basic file structure of a lesana collection,
+including a ``settings.yaml`` skeleton and it will initialize a git
+repository (use ``--no-git`` to skip this part and ignore all further
+git commands).
+
+It will then open ``settings.yaml`` in an editor: fill in your list of
+fields and all other data, save and exit.
+You are now ready to commit the configuration for your new collection::
+
+    git commit -m 'Collection settings'
+
+An empty collection is not very interesting: let us start adding new
+entries::
+
+   lesana new
+
+It will again open an editor on a skeleton of entry where you can fill
+in the values. When you close the editor it will print the entry id,
+that you can use e.g. to edit again the same entry::
+
+   lesana edit $ENTRY_ID
+
+After you've added a few entries, you can now search for some word that
+you entered in one of the indexed fields::
+
+   lesana search some words
+
+this will also print the entry ids of matching items, so that you can
+open them with ``lesana edit``.
+
+If you're using git, entries will be autoadded to the staging area, but
+you need to commit them, so that you can choose how often you do so.
+
+Search results are limited by default to 12 matches; to get all results
+for your query you can use the option ``--all``. This is especially
+useful when passing the results to a template::
+
+   lesana search --template templates/my_report.html --all \
+       some search terms \
+       > some_search_terms-report.html
+
+will generate an html file based on the jinja2 template
+``templates/my_report.html`` with all the entries found for those search
+terms.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index fbc0ce9..27352ca 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -10,6 +10,10 @@ Welcome to lesana's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   getting_started_command_line
+   moving_data_between_collections
+   promises
+
    reference/modules
 
 
diff --git a/docs/source/moving_data_between_collections.rst b/docs/source/moving_data_between_collections.rst
new file mode 100644
index 0000000..23c693e
--- /dev/null
+++ b/docs/source/moving_data_between_collections.rst
@@ -0,0 +1,41 @@
+*******************************
+Moving Data between Collections
+*******************************
+
+Entries can be exported from a lesana collection to another using the
+``lesana export`` command and a jinja2 template.
+
+The template should generate a yaml file that is a valid lesana entry
+for the destination collection and it can use the fields of the starting
+collection as variables. The variable ``entry`` is also available and
+gives complete access to the entry of the original collection, so fields
+with names that aren't valid jinja templates can be accessed as
+``entry.data[<field-name>]``.
+
+E.g. to convert between a collection with fields ``name``,
+``short-desc``, ``desc`` to a collection with fields ``name``,
+``description`` one could use the following template::
+
+   name: {{ name }}
+   description: |
+       {{ entry.data.[short-desc] }}
+
+       {{ desc | indent(width=4, first=False) }}
+
+From the origin collection you can then run the command::
+
+   lesana export <path/to/destination/collection> <path/to/template>
+
+to export all entries.
+
+You can also export just a subset of entries by adding a xapian query
+with the parameter ``--query``; you can test the search using::
+
+   lesana search --all <some search terms>
+
+and then actually run the export with::
+
+   lesana search --query '<some search terms>' <destination> <template>
+
+note that in this second command the spaces in the search query have to
+be protected from the shell.
diff --git a/docs/source/promises.rst b/docs/source/promises.rst
new file mode 100644
index 0000000..6a3b04e
--- /dev/null
+++ b/docs/source/promises.rst
@@ -0,0 +1,36 @@
+********
+Promises
+********
+
+Semantic versioning
+===================
+
+This project uses semver_.
+
+.. _semver: http://semver.org/
+
+Collection format stability
+===========================
+
+Future versions of lesana will be able to read collections written by
+older versions.
+
+Older versions in the same mayor release will also be able to work
+concurrently on the same repository.
+
+If in the future a change of formats will be required, conversions
+scripts will be written in a way that will make them as stable as
+possibile, and will have enought test data to keep them maintained for
+the time being.
+
+Disposable cache
+================
+
+Contrary to the yaml files, the xapian cache is considered disposable:
+from time to time there may be a need to delete the cache and reindex
+everything, either because of an upgrade or to perform repository
+mainteinance.
+
+Of course, effort will be made to reduce the need for this so that it
+only happens sporadically, but it will probably never completely
+disappear.
-- 
cgit v1.2.3