From 8453c268f55ef7cfbc2fe6a6bc5c8ca7a67c8880 Mon Sep 17 00:00:00 2001 From: Elena ``of Valhalla'' Grandi 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 (limited to 'docs') 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[]``. - -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 - -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 - -and then actually run the export with:: - - lesana search --query ''