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/getting_started_command_line.rst           | 61 ------------------------
 docs/moving_data_between_collections.rst        | 40 ----------------
 docs/promises.rst                               | 35 --------------
 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 ++++++++++++++
 7 files changed, 143 insertions(+), 136 deletions(-)
 delete mode 100644 docs/getting_started_command_line.rst
 delete mode 100644 docs/moving_data_between_collections.rst
 delete mode 100644 docs/promises.rst
 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

diff --git a/docs/getting_started_command_line.rst b/docs/getting_started_command_line.rst
deleted file mode 100644
index d2e4378..0000000
--- a/docs/getting_started_command_line.rst
+++ /dev/null
@@ -1,61 +0,0 @@
-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/moving_data_between_collections.rst b/docs/moving_data_between_collections.rst
deleted file mode 100644
index 170b391..0000000
--- a/docs/moving_data_between_collections.rst
+++ /dev/null
@@ -1,40 +0,0 @@
-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/promises.rst b/docs/promises.rst
deleted file mode 100644
index 92ab5aa..0000000
--- a/docs/promises.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-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.
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