aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorElena ``of Valhalla'' Grandi <valhalla@trueelena.org>2019-09-22 17:37:30 +0200
committerElena ``of Valhalla'' Grandi <valhalla@trueelena.org>2019-09-22 17:37:30 +0200
commit4a38a4839890b6cb45ccaee63829b815383c6f20 (patch)
treef5968918fb59c2e6ff0450fc7e2e228cc8ff4faa
parent299398ce87fd67a4a24074719b764ac5af300331 (diff)
Documentation for the export subcommand
-rw-r--r--docs/moving_data_between_collections.rst40
1 files changed, 40 insertions, 0 deletions
diff --git a/docs/moving_data_between_collections.rst b/docs/moving_data_between_collections.rst
new file mode 100644
index 0000000..170b391
--- /dev/null
+++ b/docs/moving_data_between_collections.rst
@@ -0,0 +1,40 @@
+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.