From 54185616ef81fa1da57b3d3bad4d9f5f71c0b07c Mon Sep 17 00:00:00 2001 From: Elena ``of Valhalla'' Grandi Date: Thu, 8 Oct 2020 20:42:54 +0200 Subject: Split documentation by target --- docs/source/contrib/index.rst | 10 ++++ docs/source/devel/index.rst | 13 +++++ docs/source/devel/promises.rst | 36 +++++++++++++ docs/source/getting_started_command_line.rst | 62 ---------------------- docs/source/index.rst | 6 +-- docs/source/moving_data_between_collections.rst | 41 -------------- docs/source/promises.rst | 36 ------------- docs/source/user/getting_started_command_line.rst | 62 ++++++++++++++++++++++ docs/source/user/index.rst | 12 +++++ .../user/moving_data_between_collections.rst | 41 ++++++++++++++ 10 files changed, 177 insertions(+), 142 deletions(-) create mode 100644 docs/source/contrib/index.rst create mode 100644 docs/source/devel/index.rst create mode 100644 docs/source/devel/promises.rst delete mode 100644 docs/source/getting_started_command_line.rst delete mode 100644 docs/source/moving_data_between_collections.rst delete mode 100644 docs/source/promises.rst create mode 100644 docs/source/user/getting_started_command_line.rst create mode 100644 docs/source/user/index.rst create mode 100644 docs/source/user/moving_data_between_collections.rst diff --git a/docs/source/contrib/index.rst b/docs/source/contrib/index.rst new file mode 100644 index 0000000..70d1e1c --- /dev/null +++ b/docs/source/contrib/index.rst @@ -0,0 +1,10 @@ +########################### + Contributor Documentation +########################### + +Documentation that is useful for contributors of lesana. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + diff --git a/docs/source/devel/index.rst b/docs/source/devel/index.rst new file mode 100644 index 0000000..cdaa532 --- /dev/null +++ b/docs/source/devel/index.rst @@ -0,0 +1,13 @@ +######################### + Developer Documentation +######################### + +Documentation that is useful for developers who are using lesana as a +library. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + promises + diff --git a/docs/source/devel/promises.rst b/docs/source/devel/promises.rst new file mode 100644 index 0000000..6a3b04e --- /dev/null +++ b/docs/source/devel/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. diff --git a/docs/source/getting_started_command_line.rst b/docs/source/getting_started_command_line.rst deleted file mode 100644 index 0c4d507..0000000 --- a/docs/source/getting_started_command_line.rst +++ /dev/null @@ -1,62 +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/source/index.rst b/docs/source/index.rst index fe3c821..8f5f8fa 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -20,9 +20,9 @@ The author can be contacted via email: webmaster AT trueelena DOT org. :maxdepth: 2 :caption: Contents: - getting_started_command_line - moving_data_between_collections - promises + user/index + devel/index + contrib/index man/index diff --git a/docs/source/moving_data_between_collections.rst b/docs/source/moving_data_between_collections.rst deleted file mode 100644 index 23c693e..0000000 --- a/docs/source/moving_data_between_collections.rst +++ /dev/null @@ -1,41 +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 ''