Restructure documentation

Signed-off-by: Roberto Rosario <roberto.rosario@mayan-edms.com>

docs/chapters/indexes/examples.txt

@@ -0,0 +1,125 @@
+==============
+Index examples
+==============
+
+Index of document types
+=======================
+
+.. admonition:: Permissions required
+    :class: warning
+
+    - The "Create new document indexes" permission is required for this action.
+    - The "Edit document indexes" permission is required for this action, globally
+      of via an ACL for a document index.
+    - The "Edit document types" permission is required for this action, globally
+      of via an ACL for a document type.
+
+
+This index will create one level for each document type in the system and place
+links to the document of each respective type.
+
+#. Go to the :menuselection:`System --> Setup --> Indexes` menu.
+#. Create a new index using :guilabel:`Actions` > :guilabel:`Create new`.
+#. Give it a label to describe it, and an internal name. The internal name is
+   used when referencing this index in other parts of the system.
+#. Press the :guilabel:`Template` link of the newly created index.
+#. Select :guilabel:`New child node` to create a new level in which the
+   following template code will be entered.
+   ::
+
+       {{ document.document_type }}
+
+#. Save the template.
+#. Click on :guilabel:`Document types` and associate this index with
+   existing document types in the system.
+#. Finally go to :menuselection:`Tools --> Rebuild indexes` to execute the
+   index template. The rebuild process is only necessary when changes are
+   made to the index templates. Otherwise they update automatically whenever
+   a new document is uploaded or existing documents properties are modified.
+#. A new index should appear under :menuselection:`Indexes` menu.
+
+You can also program different behavior based on the different document types,
+by use a comparison and a conditional statement. As the document_type itself
+is not a string you cannot directly use that for that comparison. You will have
+to use the label of the document type.
+
+For example::
+
+    {% if document.document_type.label == "Invoice" or document.document_type.label == "Letter" %}
+    Correspondence
+    {% else %}
+    {{ document.document_type }}
+    {% endif %}
+
+This will create and index level for each document type. Except for documents
+of types "Invoice" and "Letter", these will now go into the level "Correspondence".
+
+
+Index document by department, taken from the first character of the invoice number metadata
+===========================================================================================
+
+Requires one index node with the template::
+
+    {% if document.metadata_value_of.invoice_number.0 == "A" %}Accounting
+    {% if document.metadata_value_of.invoice_number.0 == "H" %}Human Resources
+    {% endif %}
+
+
+Nested date index from a date contained in a metadata
+=====================================================
+
+Assuming the metadata type is named **date_issued** with a date format
+of YYYY-MM-DD. The target is to have two levels: one for years and another
+sub level for months.
+
+**First level: Year**
+::
+
+    {{ document.metadata_value_of.date_issued|slice:"0:4" }}
+
+
+**Second level: Months**
+::
+
+    {{ document.metadata_value_of.date_issued|slice:"5:7" }}
+
+
+**Optional: Third level: Day**
+::
+
+    {{ document.metadata_value_of.date_issued|slice:"8:10" }}
+
+
+Index by OCR content
+====================
+
+This example indexes documents in a "quarterly report" level if they have the
+fragment “quarterly report” in the OCR text::
+
+    {% if "quarterly report" in document.latest_version.ocr_content|join:" "|lower %}Quarterly reports{% endif %}
+
+The same applies to text content extracted for the document::
+
+    {% if "quarterly report" in document.latest_version.content|join:" "|lower %}Quarterly reports{% endif %}
+
+
+
+Index documents not found in any cabinet
+========================================
+::
+
+    {% if document.cabinets.count == 0 %}No Cabinets{% endif %}
+
+
+Index documents not tagged
+==========================
+::
+
+    {% if document.tags.count == 0 %}No Tags{% endif %}
+
+
+Index documents specifically, by the year of a metadata field otherwise by their uploaded year
+==============================================================================================
+::
+
+    {% for tag in document.tags.all %}{% if tag.label == "Taxes" %}{% if document.metadata_value_of.tax_year|length_is:"4" %}{{ document.metadata_value_of.tax_year }}{% else %}{{ document.date_added|date:"Y" }}{% endif %}{% endif %}{% endfor %}

docs/chapters/indexes/index.txt

@@ -0,0 +1,23 @@
+.. index:: Indexes
+
+================
+Document indexes
+================
+
+Document indexes are a multi level structure similar to folder in a filesystem,
+however the hierarchy of the levels is automatically created, updated, or deleted
+based on rules set by the administrator.
+
+- :doc:`indexes`
+- :doc:`examples`
+- :doc:`mirroring`
+
+.. toctree::
+  :hidden:
+
+  indexes
+  mirroring
+  examples
+
+
+

docs/chapters/indexes/indexes.txt

@@ -0,0 +1,78 @@
+===============
+Index structure
+===============
+
+Indexes are an automatic method to hierarchically organize documents in
+relation to their properties (:doc:`../metadata`, label, MIME type,
+etc). To use indexes you need to first create an index template. Once created,
+associate the index to one or more :doc:`../document_types`.
+
+Index are hierarchical models so a tree template needs to be specified for them.
+This tree template will contain references to document metadata or properties
+that will be replaced with the actual value for those metadata or properties.
+
+Example:
+
+- Document type: ``Product sheet``
+- Metadata type: ``Product year``, associated as a required metadata for the document type ``Product sheet``.
+
+- Index: ``Product sheets per year``, and associated to the document type ``Product sheet``.
+- Index slug: ``product-sheets-per-year``. Slugs are internal unique identifiers that can be used by other Mayan EDMS modules to reference each index.
+- Index tree template as follows:
+
+.. blockdiag::
+
+   blockdiag {
+      default_shape = roundedbox
+      span_width = 30;
+
+      index [ label = 'Product sheets per year', width=180 ];
+      root [ label = 'Root (Has document links? No)', width=450];
+      level_2 [ label = '{{ document.metadata_value_of.product_year }} (Has document links? Yes)', width=450];
+
+      group {
+        label = "Tree template";
+        color = "#dddddd";
+        style = dashed;
+        root; level_2;
+      }
+
+      index -> root
+      root -> level_2 [folded];
+   }
+
+Now every time a new ``Product sheet`` is uploaded a hierarchical unit with the value
+of the metadata type ``Product year`` is created and a link to the uploaded ``Product sheet`` added to it.
+
+Example:
+
+Suppose three ``Product sheets`` are uploaded with the following values as their
+``Product year`` metadata: 2001, 2002, 2001 respectively. The result index
+that will be generate based on the tree template would be as follows:
+
+.. blockdiag::
+
+   blockdiag {
+      default_shape = roundedbox
+
+      index [ label = 'Product sheets per year', width=180 ];
+      year_1 [ label = '2001', width = 60 ];
+      year_2 [ label = '2002', width = 60 ];
+      document_1 [ label = 'Product A data sheet (2001)', width = 200 ];
+      document_2 [ label = 'Product B data sheet (2002)', width = 200 ];
+      document_3 [ label = 'Product C data sheet (2001)', width = 200 ];
+
+      group {
+        label = "Index content";
+        color = "#dddddd";
+        style = dashed;
+        year_1, year_2, document_1, document_2, document_3;
+      }
+
+      index -> year_1;
+      index -> year_2;
+      year_1 -> document_1;
+      year_2 -> document_2;
+      year_1 -> document_3;
+
+   }

docs/chapters/indexes/mirroring.txt

@@ -0,0 +1,35 @@
+=========
+Mirroring
+=========
+
+Indexes can be exported as `FUSE <https://en.wikipedia.org/wiki/Filesystem_in_Userspace>`_
+filesystems. Using the management command ``mountindex`` we could export the
+previous example index as follows::
+
+    mkdir -p ~/indexes/products
+    mayan-edms.py mountindex product-sheets-per-year ~/indexes/products
+
+The ``~/indexes/products`` directory will now have a directory and files structure
+identical to that of the index. Once indexes are mounted with this command, they
+behave like any other filesystem directory and can even be further shared
+via the network with network file system software like
+`Samba <https://www.samba.org/>`_ or
+`NFS <https://en.wikipedia.org/wiki/Network_File_System>`_.
+
+.. blockdiag::
+
+    blockdiag {
+        orientation = portrait
+        span_width = 200;
+
+        index [ label = 'Product sheets per year', width=180 ];
+        block_device [ height = 100, label = "Block device\n(Hard drive)", shape = flowchart.database ];
+        network [ label = "Network", shape = cloud ];
+        user [ label = "Users", shape = actor ];
+
+        index -> block_device [ label = "mirroring", fontsize = 8 ];
+        block_device -> network -> user;
+   }
+
+Indexes and mirrored indexes are Read Only as they are generated as a result of
+prior activities like document uploads, metadata changes.