Split documentation by target

3 files changed, 115 insertions, 0 deletions

diff --git a/docs/source/user/getting_started_command_line.rst b/docs/source/user/getting_started_command_line.rst
new file mode 100644
index 0000000..0c4d507
--- /dev/null
+++ b/docs/source/user/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/user/index.rst b/docs/source/user/index.rst
new file mode 100644
index 0000000..75aa1dd
--- /dev/null
+++ b/docs/source/user/index.rst
@@ -0,0 +1,12 @@
+####################
+ User Documentation
+####################
+
+Documentation that is useful for everybody.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   getting_started_command_line
+   moving_data_between_collections
diff --git a/docs/source/user/moving_data_between_collections.rst b/docs/source/user/moving_data_between_collections.rst
new file mode 100644
index 0000000..23c693e
--- /dev/null
+++ b/docs/source/user/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.