matthias/mayan-edms
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Reorganize documentation into topics and chapters. Add new material from Wiki.

Browse Source 
Signed-off-by: Roberto Rosario <roberto.rosario.gonzalez@gmail.com>
This commit is contained in:
Roberto Rosario
2018-10-15 06:03:04 -04:00
parent 7cd62b5a85
commit e6c43bebf5
59 changed files with 1377 additions and 895 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/topics/acls.rst → docs/chapters/acls.rst
View File

@@ -1,6 +1,6 @@
====================
********************
Access control lists
====================
********************
Besides the permissions system explained in :doc:`permissions`, Mayan EDMS
provides per object permission granting. This feature is used to grant a

4
docs/topics/app_creation.rst → docs/chapters/app_creation.rst
View File

@@ -1,6 +1,6 @@
============
************
App creation
============
************
Mayan EDMS apps are essentially Django app with some extra code to register
navigation, permissions and other relationships.

4
docs/topics/backups.rst → docs/chapters/backups.rst
View File

@@ -1,6 +1,6 @@
=======
*******
Backups
=======
*******
To backup your install of Mayan EDMS just copy the actual document files and
the database content. If you are using the default storage backend, the

56
docs/topics/caa_entity.rst → docs/chapters/caa_entity.rst
View File

@@ -1,6 +1,6 @@
==================================================
**************************************************
Mayan EDMS Entity Contributor Assignment Agreement
==================================================
**************************************************
Thank you for your interest in contributing to Mayan EDMS ("We" or "Us").
@@ -11,8 +11,9 @@ caa@mayan-edms.com. This is a legally binding document, so please read it
carefully before agreeing to it. The Agreement may cover more than one
software project managed by Us.
1. Definitions
--------------
==============
"You" means any Legal Entity on behalf of whom a Contribution has been received
by Us. "Legal Entity" means an entity which is not a natural person.
"Affiliates" means other Legal Entities that control, are controlled by, or
@@ -50,10 +51,12 @@ designated in writing by You as "Not a Contribution."
"Effective Date" means the date You execute this Agreement or the date You
first Submit a Contribution to Us, whichever is earlier.
2. Grant of Rights
------------------
==================
2.1 Copyright Assignment
~~~~~~~~~~~~~~~~~~~~~~~~
------------------------
a. At the time the Contribution is Submitted, You assign to Us all right, title,
and interest worldwide in all Copyright covering the Contribution; provided
@@ -77,7 +80,8 @@ d. Upon such transfer of rights to Us, the Contribution will be licenses under
the terms of the Material.
2.2 Patent License
~~~~~~~~~~~~~~~~~~
------------------
For patent claims including, without limitation, method, process, and apparatus
claims which You or Your Affiliates own, control or have the right to grant,
now or in the future, You grant to Us a perpetual, worldwide, non-exclusive,
@@ -90,30 +94,36 @@ the licensed rights infringes such patent claims; and provided that this license
is conditioned upon compliance with Section 2.3.
2.3 Outbound License
~~~~~~~~~~~~~~~~~~~~
--------------------
As a condition on the grant of rights in Sections 2.1 and 2.2, We agree to
license the Contribution only under the terms of the license or licenses which
We are using on the Submission Date for the Material (including any rights to
adopt any future version of a license if permitted).
2.4 Moral Rights
~~~~~~~~~~~~~~~~
----------------
If moral rights apply to the Contribution, to the maximum extent permitted by
law, You waive and agree not to assert such moral rights against Us or our
successors in interest, or any of our licensees, either direct or indirect.
2.5 Our Rights
~~~~~~~~~~~~~~
--------------
You acknowledge that We are not obligated to use Your Contribution as part of
the Material and may decide to include any Contribution We consider appropriate.
2.6 Reservation of Rights
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
Any rights not expressly assigned or licensed under this section are expressly
reserved by You.
3. Agreement
------------
============
You confirm that:
a. You have the legal authority to enter into this Agreement.
@@ -126,7 +136,8 @@ c. The grant of rights under Section 2 does not violate any grant of rights
4. Disclaimer
-------------
=============
EXCEPT FOR THE EXPRESS WARRANTIES IN SECTION 3, THE CONTRIBUTION IS PROVIDED
"AS IS". MORE PARTICULARLY, ALL EXPRESS OR IMPLIED WARRANTIES INCLUDING,
WITHOUT LIMITATION, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
@@ -134,18 +145,23 @@ PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY DISCLAIMED BY YOU TO US
AND BY US TO YOU. TO THE EXTENT THAT ANY SUCH WARRANTIES CANNOT BE DISCLAIMED,
SUCH WARRANTY IS LIMITED IN DURATION TO THE MINIMUM PERIOD PERMITTED BY LAW.
5. Consequential Damage Waiver
------------------------------
==============================
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL YOU OR US
BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF ANTICIPATED SAVINGS, LOSS OF DATA,
INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL AND EXEMPLARY DAMAGES ARISING OUT
OF THIS AGREEMENT REGARDLESS OF THE LEGAL OR EQUITABLE THEORY (CONTRACT, TORT
OR OTHERWISE) UPON WHICH THE CLAIM IS BASED.
6. Miscellaneous
----------------
================
6.1 Jurisdiction
~~~~~~~~~~~~~~~~
----------------
This Agreement will be governed by and construed in accordance with the laws of
Puerto Rico excluding its conflicts of law provisions. Under certain circumstances,
the governing law in this section might be superseded by the United Nations
@@ -155,18 +171,18 @@ Agreement and, thus, exclude the application of the UN Convention in its
entirety to this Agreement.
6.2 Acceptance
~~~~~~~~~~~~~~
--------------
This Agreement sets out the entire agreement between You and Us for Your
Contributions to Us and overrides all other agreements or understandings.
6.3 Third parties
~~~~~~~~~~~~~~~~~
-----------------
If You or We assign the rights or obligations received through this Agreement
to a third party, as a condition of the assignment, that third party must
agree in writing to abide by all the rights and obligations in the Agreement.
6.4 Unmet responsabilities
~~~~~~~~~~~~~~~~~~~~~~~~~~
6.4 Unmet responsibilities
--------------------------
The failure of either party to require performance by the other party of any
provision of this Agreement in one situation shall not affect the right of a
party to require such performance at any time in the future. A waiver of
@@ -175,7 +191,7 @@ waiver of the performance of the provision in the future or a waiver of the
provision in its entirety.
6.5 Continuation
~~~~~~~~~~~~~~~~
----------------
If any provision of this Agreement is found void and unenforceable, such
provision will be replaced to the extent possible with a provision that comes
closest to the meaning of the original provision and which is enforceable.

63
docs/topics/caa_individual.rst → docs/chapters/caa_individual.rst
View File

@@ -1,6 +1,6 @@
======================================================
******************************************************
Mayan EDMS Individual Contributor Assignment Agreement
======================================================
******************************************************
Thank you for your interest in contributing to Mayan EDMS ("We" or "Us").
@@ -12,7 +12,7 @@ carefully before agreeing to it. The Agreement may cover more than one
software project managed by Us.
1. Definitions
--------------
==============
"You" means the individual who Submits a Contribution to Us.
@@ -44,10 +44,11 @@ or otherwise designated in writing by You as "Not a Contribution."
Submit a Contribution to Us, whichever is earlier.
2. Grant of Rights
------------------
==================
2.1 Copyright Assignment
~~~~~~~~~~~~~~~~~~~~~~~~
------------------------
a. At the time the Contribution is Submitted, You assign to Us all right,
title, and interest worldwide in all Copyright covering the Contribution;
provided that this transfer is conditioned upon compliance with Section 2.3.
@@ -69,8 +70,10 @@ c. To the extent that any of the rights in Section 2.1(a) can neither be
d. Upon such transfer of rights to Us, the Contribution will be licenses under
the terms of the Material.
2.2 Patent License
~~~~~~~~~~~~~~~~~~
------------------
For patent claims including, without limitation, method, process, and apparatus
claims which You own, control or have the right to grant, now or in the future,
You grant to Us a perpetual, worldwide, non-exclusive, transferable, royalty-free,
@@ -81,31 +84,40 @@ the Material (and portions of such combination). This license is granted only
to the extent that the exercise of the licensed rights infringes such patent claims;
and provided that this license is conditioned upon compliance with Section 2.3.
2.3 Outbound License
~~~~~~~~~~~~~~~~~~~~
--------------------
As a condition on the grant of rights in Sections 2.1 and 2.2, We agree to
license the Contribution only under the terms of the license or licenses which
We are using on the Submission Date for the Material (including any rights to
adopt any future version of a license if permitted).
2.4 Moral Rights
~~~~~~~~~~~~~~~~
----------------
If moral rights apply to the Contribution, to the maximum extent permitted by law,
You waive and agree not to assert such moral rights against Us or our successors
in interest, or any of our licensees, either direct or indirect.
2.5 Our Rights
~~~~~~~~~~~~~~
--------------
You acknowledge that We are not obligated to use Your Contribution as part of
the Material and may decide to include any Contribution We consider appropriate.
2.6 Reservation of Rights
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
Any rights not expressly assigned or licensed under this section are expressly
reserved by You.
3. Agreement
------------
============
You confirm that:
a. You have the legal authority to enter into this Agreement.
@@ -119,8 +131,10 @@ c. The grant of rights under Section 2 does not violate any grant of rights
version of this document. If You are less than eighteen years old, please have
Your parents or guardian sign the Agreement.
4. Disclaimer
-------------
=============
EXCEPT FOR THE EXPRESS WARRANTIES IN SECTION 3, THE CONTRIBUTION IS PROVIDED
"AS IS". MORE PARTICULARLY, ALL EXPRESS OR IMPLIED WARRANTIES INCLUDING, WITHOUT
LIMITATION, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
@@ -128,18 +142,23 @@ PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY DISCLAIMED BY YOU TO US AND BY US
TO YOU. TO THE EXTENT THAT ANY SUCH WARRANTIES CANNOT BE DISCLAIMED, SUCH
WARRANTY IS LIMITED IN DURATION TO THE MINIMUM PERIOD PERMITTED BY LAW.
5. Consequential Damage Waiver
------------------------------
==============================
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL YOU OR US
BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF ANTICIPATED SAVINGS, LOSS OF DATA,
INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL AND EXEMPLARY DAMAGES ARISING OUT
OF THIS AGREEMENT REGARDLESS OF THE LEGAL OR EQUITABLE THEORY (CONTRACT, TORT
OR OTHERWISE) UPON WHICH THE CLAIM IS BASED.
6. Miscellaneous
----------------
================
6.1 Jurisdiction
~~~~~~~~~~~~~~~~
----------------
This Agreement will be governed by and construed in accordance with the laws of
Puerto Rico excluding its conflicts of law provisions. Under certain circumstances,
the governing law in this section might be superseded by the United Nations
@@ -149,18 +168,21 @@ Agreement and, thus, exclude the application of the UN Convention in its
entirety to this Agreement.
6.2 Acceptance
~~~~~~~~~~~~~~
--------------
This Agreement sets out the entire agreement between You and Us for Your
Contributions to Us and overrides all other agreements or understandings.
6.3 Third parties
~~~~~~~~~~~~~~~~~
-----------------
If You or We assign the rights or obligations received through this Agreement
to a third party, as a condition of the assignment, that third party must
agree in writing to abide by all the rights and obligations in the Agreement.
6.4 Unmet responsabilities
~~~~~~~~~~~~~~~~~~~~~~~~~~
6.4 Unmet responsibilities
--------------------------
The failure of either party to require performance by the other party of any
provision of this Agreement in one situation shall not affect the right of a
party to require such performance at any time in the future. A waiver of
@@ -169,7 +191,8 @@ waiver of the performance of the provision in the future or a waiver of the
provision in its entirety.
6.5 Continuation
~~~~~~~~~~~~~~~~
----------------
If any provision of this Agreement is found void and unenforceable,
such provision will be replaced to the extent possible with a provision that
comes closest to the meaning of the original provision and which is enforceable.

14
docs/chapters/cabinets.rst Normal file
View File

@@ -0,0 +1,14 @@
Cabinets
========
Cabinets are a multi-level method to organize documents. Each cabinet can
contain documents as well as other sub level cabinets. Cabinets can
be added from the :menuselection:`Cabinets --> Add new` menu.
With a cabinet structure created, the next step is to add documents to them.
To add documents to a cabinet, select the cabinet tab of a document, and
select :menuselection:`Actions --> Add to cabinets` link.
Documents can also be added in bulk to one or more cabinets from any view
that lists documents.

4
docs/topics/checkouts.rst → docs/chapters/checkouts.rst
View File

@@ -1,6 +1,6 @@
=========
*********
Checkouts
=========
*********
Checkouts are a way to block certain accesses or actions of a document for a
period of time.

4
docs/topics/deploying.rst → docs/chapters/deploying.rst
View File

@@ -1,8 +1,8 @@
.. _deploying:
==================
******************
Direct deployments
==================
******************
Mayan EDMS should be deployed like any other Django_ project and
preferably using virtualenv_. Below are some ways to deploy and use Mayan EDMS.

479
docs/chapters/development.rst Normal file
View File

@@ -0,0 +1,479 @@
.. _development:
***********
Development
***********
Mayan EDMS is under active development, and contributions are welcome.
If you have a feature request, suggestion or bug report, please open a new
issue on the `GitLab issue tracker`_. To submit patches, please send a merge
request on GitLab_.
.. _GitLab: https://gitlab.com/mayan-edms/mayan-edms/
.. _`GitLab issue tracker`: https://gitlab.com/mayan-edms/mayan-edms/issues
Project philosophies
====================
How to think about Mayan EDMS when doing changes or adding new features;
why things are the way they are in Mayan EDMS:
- Functionality must be as market/sector independent as possible, code for the
95% of use cases.
- Each user must be able to configure and customize it to their needs after
install.
- Abstract as much as possible, each app must be an expert in just one thing,
for other things they should use the API/classes/functions of other apps.
- Assume as little as possible about anything outside the project
(hardware, OS, storage).
- Provide Python based abstraction so that a default install runs with a single
step.
- No hard dependencies on binaries unless there is no other choice.
- Provide “drivers” or switchable backends to allow users to fine tune the
installation.
- Call to binaries only when there is no other choice or the Python choices are
not viable/mature/efficient.
- Each app is as independent and self contained as possible. Exceptions, the
basic requirements: navigation, permissions, common, main.
- If an app is meant to be used by more than one other app, it should be as
generic as possible in regard to the project and another app will bridge the functionality.
- Example: since indexing (document_indexing) only applies to documents, the
app is specialized and depends on the documents app.
Coding conventions
==================
Follow PEP8
-----------
Whenever possible, but don't obsess over things like line length:
.. code-block:: bash
$ flake8 --ignore=E501,E128,E122 |less
To perform automatic PEP8 checks, install flake8's git hook using:
.. code-block:: bash
$ flake8 --install-hook git
Imports
-------
Import order should be:
- Standard Python modules
- Installed Python modules
- Core Django modules
- Installed Django modules
- Mayan EDMS modules
- Local imports
Example:
.. code-block:: bash
from __future__ import absolute_import
# Standard Python library
import base64
# 3rd party installed Python libraries
import requests
# Django core modules
from django.db.models import Q
from django.template.defaultfilters import slugify
from django.utils.translation import ugettext
from django.utils.translation import ugettext_lazy as _
# 3rd party installed Django libraries
from rest_framework import APIView
# Mayan apps
from metadata.classes import MetadataClass
# Local app imports (relative)
from .conf.settings import (
AVAILABLE_INDEXING_FUNCTIONS,
MAX_SUFFIX_COUNT, SLUGIFY_PATHS
)
from .exceptions import MaxSuffixCountReached
from .filesystem import (
fs_create_index_directory, fs_create_document_link,
fs_delete_document_link, fs_delete_index_directory,
assemble_suffixed_filename
)
from .models import Index, IndexInstanceNode, DocumentRenameCount
All local app module imports are in relative form. Local app module name is to
be referenced as little as possible, unless required by a specific feature,
trick, restriction (e.g., Runtime modification of the module's attributes).
Incorrect:
.. code-block:: bash
# documents app views.py model
from documents.models import Document
Correct:
.. code-block:: bash
# documents app views.py model
from .models import Document
Dependencies
------------
Mayan EDMS apps follow a hierarchical model of dependency. Apps import from
their parents or siblings, never from their children. Think plugins. A parent
app must never assume anything about a possible existing child app. The
documents app and the Document model are the basic entities; they must never
import anything else. The common and main apps are the base apps.
Variables
---------
Naming of variables should follow a Major to Minor convention, usually
including the purpose of the variable as the first piece of the name, using
underscores as spaces. camelCase is not used in Mayan EDMS.
Examples:
Links:
.. code-block:: bash
link_document_page_transformation_list = ...
link_document_page_transformation_create = ...
link_document_page_transformation_edit = ...
link_document_page_transformation_delete = ...
Constants:
.. code-block:: bash
PERMISSION_SMART_LINK_VIEW = ...
PERMISSION_SMART_LINK_CREATE = ...
PERMISSION_SMART_LINK_DELETE = ...
PERMISSION_SMART_LINK_EDIT = ...
Classes:
.. code-block:: bash
class Document(models.Model):
class DocumentPage(models.Model):
class DocumentPageTransformation(models.Model):
class DocumentType(models.Model):
class DocumentTypeFilename(models.Model):
Strings
-------
Quotation character used in Mayan EDMS for strings is the single quote.
Double quote is used for multiple line comments or HTML markup.
Migrations
----------
Migrations should do only one thing (eg: either create a table, move data to a
new table or remove an old table) to aid retrying on failure.
General
-------
Code should appear in their modules in alphabetic order or in their order of
importance if it makes more sense for the specific application. This makes
visual scanning easier on modules with a large number of imports, views or
classes. Class methods that return a value should be pretended with a
``get_`` to differentiate from an object’s properties. When a variable refers
to a file it should be named as follows:
- filename: The file’s name and extension only.
- filepath: The entire path to the file including the filename.
- path: A path to a directory.
Flash messages should end with a period as applicable for the language.
Only exception is when the tail of the message contains an exceptions message
as passed directly from the exception object.
Source Control
==============
Mayan EDMS source is controlled with Git_.
The project is publicly accessible, hosted and can be cloned from **GitLab** using::
$ git clone https://gitlab.com/mayan-edms/mayan-edms.git
Git branch structure
--------------------
Mayan EDMS follows a simplified model layout based on Vincent Driessen's
`Successful Git Branching Model`_ blog post.
``develop``
The "next release" branch, likely unstable.
``master``
Current production release (|version|).
``feature/``
Unfinished/unmerged feature.
``series/``
Released versions.
Each release is tagged separately.
When submitting patches, please place your code in its own ``feature/`` branch
prior to opening a Merge Request on GitLab_.
.. _Git: http://git-scm.org
.. _`Successful Git Branching Model`: http://nvie.com/posts/a-successful-git-branching-model/
Steps to deploy a development version
=====================================
.. code-block:: bash
$ git clone https://gitlab.com/mayan-edms/mayan-edms.git
$ cd mayan-edms
$ git checkout development
$ virtualenv venv
$ source venv/bin/activate
$ pip install -r requirements.txt
$ ./manage.py initialsetup
$ ./manage.py runserver
Contributing changes
====================
Follow the latest contributing guidelines outlined here: https://gitlab.com/mayan-edms/mayan-edms/blob/master/CONTRIBUTING.md
Debugging
=========
Mayan EDMS makes extensive use of Django's new `logging capabilities`_.
By default debug logging for all apps is turned on. If you wish to customize
how logging is managed turn off automatic logging by setting
`COMMON_AUTO_LOGGING` to ``False`` and add the following lines to your
``settings/local.py`` file::
LOGGING = {
'version': 1,
'disable_existing_loggers': True,
'formatters': {
'verbose': {
'format': '%(levelname)s %(asctime)s %(name)s %(process)d %(thread)d %(message)s'
},
'intermediate': {
'format': '%(name)s <%(process)d> [%(levelname)s] "%(funcName)s() %(message)s"'
},
'simple': {
'format': '%(levelname)s %(message)s'
},
},
'handlers': {
'console':{
'level':'DEBUG',
'class':'logging.StreamHandler',
'formatter': 'intermediate'
}
},
'loggers': {
'documents': {
'handlers':['console'],
'propagate': True,
'level':'DEBUG',
},
'common': {
'handlers':['console'],
'propagate': True,
'level':'DEBUG',
},
}
}
Likewise, to see the debug output of the ``tags`` app, just add the following inside the ``loggers`` block::
'tags': {
'handlers':['console'],
'propagate': True,
'level':'DEBUG',
},
.. _`logging capabilities`: https://docs.djangoproject.com/en/dev/topics/logging
Documentation
=============
The documentation is written in `reStructured Text`_ format, processed with
Sphinx_, and resides in the ``docs`` directory. In order to build it, you will
first need to install the documentation editing dependencies with::
$ pip install -r requirements/documentation.txt
Then, to build an HTML version of the documentation, run the following command
from the **docs** directory::
$ make docs-serve
The generated documentation can be viewed by browsing to http://127.0.0.1:8000
or by browsing to the ``docs/_build/html`` directory.
You can also generate the documentation in formats other than HTML. Consult the
Sphinx_ documentation for more details.
.. _`reStructured Text`: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx.pocoo.org
Installable package
===================
Source file package
-------------------
This is the sequence of step used to produce an installable package:
1. Generate the packaged version (will produce dist/mayan-edms-x.y.z.tar.gz)::
$ make sdist
2. Do a test install::
$ cd /tmp
$ virtualenv venv
$ source venv/bin/activate
$ pip install <path of the Git repository>/dist/mayan-edms-x.y.z.tar.gz
$ mayan-edms.py initialsetup
$ mayan-edms.py runserver
Wheel package
-------------
1. Install the development requirements::
$ pip install -r requirements/development.txt
2. Create wheel package using the makefile::
$ make wheel
3. Do a test install::
$ cd /tmp
$ virtualenv venv
$ source venv/bin/activate
$ pip install <path of the Git repository>/dist/mayan_edms-x.y.z-py2-none-any.whl
$ mayan-edms.py initialsetup
$ mayan-edms.py runserver
Version numbering
=================
Mayan EDMS uses the Semantic Versioning (http://semver.org/) method to choose
version numbers along with Python's PEP-0440 (https://www.python.org/dev/peps/pep-0440/)
to format them.
X.YaN # Alpha release
X.YbN # Beta release
X.YrcN # Release Candidate
X.Y # Final release
Release checklist
=================
1. Check for missing migrations::
make check-missing-migrations
2. Synchronize translations::
make translations-pull
3. Compile translations::
make translations-compile
4. Write release notes.
5. Update changelog.
6. Scan the code with flake8 for simple style warnings.
7. Check README.rst format with::
python setup.py check -r -s
or with::
make check-readme
8. Bump version in `mayan/__init__.py`.
9. Bump version in `docker/version`.
10. Update requirements version in `setup.py` using:
::
make generate-setup
11. Build source package and test:
::
make test-sdist-via-docker-ubuntu
12. Build wheel package and test:
::
make test-wheel-via-docker-ubuntu
13. Tag version:
::
git tag -a vX.Y.Z -m "Version X.Y.Z"
14. Switch to the `releases` branch:
::
git checkout releases
15. Push tag upstream:
::
git push --tags
16. Push code to trigger builds:
::
git push
17. Build and upload a test release:
::
make release-test-via-docker-ubuntu
18. Build and upload a final release:
::
make release-via-docker-ubuntu

0
docs/topics/docker.rst → docs/chapters/docker.rst
View File

29
docs/topics/document_types.rst → docs/chapters/document_types.rst
View File

@@ -1,21 +1,35 @@
==============
.. _document_types:
Document types
==============
The basic unit of data in Mayan EDMS is the ``document type``. A document
type can be interpreted also as a document category, a document class, or a
document template. Document types need to be created before documents can be
document template. Every other aspect of the system will rely or be tied to
one or more document type. Create one document type for each type or class of
document you intend to upload into Mayan EDMS.
Document types need to be created before documents can be
uploaded. It is not possible to upload documents without assigning them a
document type. Examples of document type: **invoices**, **blueprints**,
**receipts**.
document type.
Document types usually mirror the type of physical, paper document they
represent.
Example document types:
* Letter
* Invoice
* Timesheet
* Blueprint
.. blockdiag::
blockdiag {
default_shape = roundedbox
document_type [ label = 'Document type' ];
documents [ label = 'Documents' ];
document_type [ label = 'each document type' ];
documents [ label = 'many documents' ];
document_type -> documents;
}
@@ -55,3 +69,6 @@ assigned when uploaded into Mayan EDMS. A document can only be of one
type at a given moment, but if needed, the type of a document can be changed.
Upon changing its type, the document will lose its previous settings and
attributes, and will inherit the settings and attributes of its new type.
Document types are create in the
:menuselection:`System --> Setup --> Document types` menu.

4
docs/topics/file_storage.rst → docs/chapters/file_storage.rst
View File

@@ -1,6 +1,6 @@
============
************
File storage
============
************
The files are stored and placed under Mayan EDMS "control" to avoid
filename clashes each file gets renamed to its ``UUID`` (Universally Unique ID),

111
docs/chapters/index_examples.rst Normal file
View File

@@ -0,0 +1,111 @@
Index examples
--------------
Index of document types
^^^^^^^^^^^^^^^^^^^^^^^
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 :menuselection:`Actions --> 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 :menuselection:`Template` link of the newly created index.
#. Select :menuselection:`New child node` to create a new level in which the
following template code will be entered.
::
{{ document.document_type }}
#. Save the template.
#. Go to :menuselection:`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 necesary 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 untagged documents
^^^^^^^^^^^^^^^^^^^^^^^^
::
{% 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 %}

6
docs/topics/indexes.rst → docs/chapters/indexes.rst
View File

@@ -1,4 +1,3 @@
=======
Indexes
=======
@@ -77,8 +76,11 @@ that will be generate based on the tree template would be as follows:
}
.. include:: ../chapters/index_examples.rst
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

36
docs/chapters/languages.rst Normal file
View File

@@ -0,0 +1,36 @@
*********
Languages
*********
The list of languages choices in the language dropdown used for documents is
based on the current ISO 639 list. This list can be quite extensive. To reduce
the number of languages available use the setting ``DOCUMENTS_LANGUAGE_CODES``,
and set it to a nested list of abbreviations. This setting can be found in the
:menuselection:`System --> Setup -> Settings -> Common` menu.
For example, to reduce the list to just English and Spanish use
::
DOCUMENTS_LANGUAGE_CODES = ('eng', 'spa')
The default language to appear on the dropdown can also be configured using::
DOCUMENTS_LANGUAGE = 'spa'
Use the correct ISO 639-3 language abbreviation (https://en.wikipedia.org/wiki/ISO_639)
as this code is used in several subsystems in Mayan EDMS such as the OCR app
to determine how to interpret the document.
If using the Docker image, these settings can also be passed to the container
as environment variables by prepending the ``MAYAN_`` suffix.
Example::
-e MAYAN_DOCUMENTS_LANGUAGE_CODES='["eng", "spa"]'
For more information check out the
:ref:`environment variables <environment_variables>` section of the
:doc:`../chapters/settings` chapter.

37
docs/chapters/mailing.rst Normal file
View File

@@ -0,0 +1,37 @@
*****************
Mailing documents
*****************
Sending emails in Mayan EDMS is controlled by two different system depending on
the type of email being sent. These are administrative emails like password
reset emails and user emails sent from the application.
Sending administrative emails
=============================
To be able to send password reset emails configure the Django email settings
via the :ref:`configuration file <configuration_file>`.
Example::
EMAIL_BACKEND: django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST: '<your smtp ip address or hostname>'
EMAIL_HOST_PASSWORD: '<your smtp password>'
EMAIL_HOST_USER: '<your smtp username>'
EMAIL_PORT: 25 # or 587 or your server's SMTP port
EMAIL_TIMEOUT:
EMAIL_USE_SSL: true
EMAIL_USE_TLS: false
For more details consult Django's documentation on the topic:
https://docs.djangoproject.com/en/1.11/ref/settings/#email-backend
Application emails
==================
To allow users to send emails or documents from within the web interface,
Mayan EDMS provides its our own email system called Mailing Profiles.
Mailing Profiles support access control per user role and can use different
email backends. Mailing Profiles are created from the
:menuselection:`System --> Setup` menu.

4
docs/topics/metadata.rst → docs/chapters/metadata.rst
View File

@@ -1,6 +1,6 @@
========
********
Metadata
========
********
Metadata is the name of the attribute of a document. The concept of metadata is
divided in two: **metadata types** (size, color, distance) and **metadata values** for

62
docs/chapters/object_storage.rst Normal file
View File

@@ -0,0 +1,62 @@
.. _object_storage:
**************
Object storage
**************
It is possible to use object storage instead of the default filesystem based
storage. One such object storage system is Amazon S3 (Simple Storage Service)
API compatible object storage. The following steps will configure Mayan EDMS
to use a S3 style storage for documents.
1. Install the django-storages and boto3 Python libraries.
* For the direct deployment method of installation use::
pip install django-storages boto3
* or if using the Docker image, add the following the command line that runs the container::
-e MAYAN_PIP_INSTALLS='django-storages boto3'
2. From the web interface navigate to the :menuselection:`System --> Setup --> Setting --> Documents` menu.
3. Locate the **DOCUMENTS_STORAGE_BACKEND** setting, press **Edit** and enter::
storages.backends.s3boto3.S3Boto3Storage
4. Save and locate the setting **DOCUMENTS_STORAGE_BACKEND_ARGUMENTS**, press **Edit** and enter::
'{access_key: <your S3 access key>, secret_key: <your S3 secret key>, bucket_name: <S3 bucket name>}'
5. Save and restart your Mayan EDMS installation for the setting to take effect.
Storage
=======
Mayan EDMS stores documents in their original file format only changing the
filename to avoid collision. For best input and output speed use a block
based local filesystem for the ``/media`` sub folder of the path specified by
the MEDIA_ROOT setting. For increased storage capacity use an object storage
filesystem like S3.
To use a S3 compatible object storage do the following:
* Install the Python packages ``django-storages`` and ``boto3``:
* Using Python::
pip install django-storages boto3
* Using Docker::
-e MAYAN_PIP_INSTALLS='django-storages boto3'
On the Mayan EDMS user interface, go to ``System``, ``Setup``, ``Settings``,
``Documents`` and change the following setting:
* ``DOCUMENTS_STORAGE_BACKEND`` to ``storages.backends.s3boto3.S3Boto3Storage``
* ``DOCUMENTS_STORAGE_BACKEND_ARGUMENTS`` to ``'{access_key: <your access key>, secret_key: <your secret key>, bucket_name: <bucket name>}'``.
Restart Mayan EDMS for the changes to take effect.

4
docs/topics/ocr_backend.rst → docs/chapters/ocr_backend.rst
View File

@@ -1,6 +1,6 @@
===========
***********
OCR backend
===========
***********
Mayan EDMS ships an OCR backend that uses the FLOSS engine Tesseract
(https://github.com/tesseract-ocr/tesseract/), but it can

4
docs/topics/permissions.rst → docs/chapters/permissions.rst
View File

@@ -1,6 +1,6 @@
===========
***********
Permissions
===========
***********
Mayan EDMS provides very fine control over which actions users can
perform. Action control works by allowing ``roles``, that are composed of

40
docs/topics/scaling_up.rst → docs/chapters/scaling_up.rst
View File

@@ -1,9 +1,9 @@
.. _scaling_up:
==========
**********
Scaling up
==========
**********
The default installation method fits most use cases. If you use case requires
more speed or capacity here are some suggestion that can help you improve the
@@ -146,38 +146,18 @@ host dedicated to serving only Mayan EDMS.
Storage
=======
Mayan EDMS stores documents in their original file format only changing the
filename to avoid collision. For best input and output speed use a block
based local filesystem for the ``/media`` sub folder of the path specified by
the MEDIA_ROOT setting. For increased storage capacity use an object storage
filesystem like S3.
To use a S3 compatible object storage do the following:
* Install the Python packages ``django-storages`` and ``boto3``:
* Using Python::
pip install django-storages boto3
* Using Docker::
-e MAYAN_PIP_INSTALLS='django-storages boto3'
On the Mayan EDMS user interface, go to ``System``, ``Setup``, ``Settings``,
``Documents`` and change the following setting:
* ``DOCUMENTS_STORAGE_BACKEND`` to ``storages.backends.s3boto3.S3Boto3Storage``
* ``DOCUMENTS_STORAGE_BACKEND_ARGUMENTS`` to ``'{access_key: <your access key>, secret_key: <your secret key>, bucket_name: <bucket name>}'``.
Restart Mayan EDMS for the changes to take effect.
For best input and output speed use a block based local filesystem on an
SSD drive for the ``/media`` sub folder. The location of the ``/media`` folder
will be specified by the ``MEDIA_ROOT`` setting.
If capacity is your bottom line, switch to an
:ref:`object storage <object_storage>` system.
Use additional hosts
====================
When one host is not enough you can use multiple hosts and share the load.
Make sure that all hosts share the ``/media`` folder as specified by the
MEDIA_ROOT setting, also the database, the broker, and the result storage.
``MEDIA_ROOT`` setting, also the database, the broker, and the result storage.
One setting that needs to be changed in this configuration is the lock
manager backend.
@@ -187,9 +167,9 @@ its own lock manager. By default the lock manager with use a simple file
based lock backend ideal for single host installations. For multiple hosts
installation the database backend must be used in other to coordinate the
resource locks between the different hosts over a share data medium. This is
accomplished by modifying the environment variable LOCK_MANAGER_BACKEND in
accomplished by modifying the environment variable ``LOCK_MANAGER_BACKEND`` in
both the direct deployment or the Docker image. Use the value
"lock_manager.backends.model_lock.ModelLock" to switch to the database
``lock_manager.backends.model_lock.ModelLock`` to switch to the database
resource lock backend. If you can also write your own lock manager backend
for other data sharing mediums with better performance than a relational
database like Redis, Memcached, Zoo Keeper.

107
docs/chapters/settings.rst Normal file
View File

@@ -0,0 +1,107 @@
Mayan EDMS can be configure via environment variables or by setting files.
.. _environment_variables:
Via environment variables
=========================
To use environment variables, lookup the name of the setting you want to
override in the "Settings" menu. The "Settings" menu is located inside the
"Setup" main menu. To pass a value via an environment variable append
``"MAYAN_"`` to the name of the settings option. For example, to change
the number of documents displayed per page (COMMON_PAGINATE_BY, by default 40),
use::
export MAYAN_COMMON_PAGINATE_BY=10
Restart Mayan EDMS and the new value will take effect. The "Settings" menu
can be used to verify if the overridden setting value is being interpreted
correctly.
.. _configuration_file:
Via YAML configuration file
===========================
.. versionadded:: 3.1
It is possible to modify the different settings by creating or editing the
``media/config.yml`` file. This file is formatted in the YAML markup language (
http://yaml.org/). Here is an example of what the looks like::
DOCUMENT_PARSING_AUTO_PARSING: true
DOCUMENT_PARSING_PDFTOTEXT_PATH: /usr/bin/pdftotext
EMAIL_BACKEND: django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST: localhost
EMAIL_HOST_PASSWORD: ''
EMAIL_HOST_USER: ''
EMAIL_PORT: 25
EMAIL_TIMEOUT: null
EMAIL_USE_SSL: false
EMAIL_USE_TLS: false
FILE_UPLOAD_MAX_MEMORY_SIZE: 2621440
HOME_VIEW: common:home
Every time Mayan EDMS is able to start correctly it will copy the ``config.yml``
and create a backup copy in the same directory named ``config_backup.yml``.
This file is used to revert to the last know configuration file known
to be valid. You can revert manually by copy the file or by using the
``revertsettings`` management command from the command line.
Via Python settings files
=========================
Another way to configure Mayan EDMS is via Python-style, settings files.
If Mayan EDMS was installed using the Python package a ``mayan_settings``
folder will created for this purpose. If you installed Mayan EDMS
according to the :ref:`deploying` instructions provided in this
documentation your ``mayan_settings`` folder should be located in the directory:
``/usr/share/mayan-edms/mayan/media/mayan_settings``.
If Mayan EDMS was installed using Docker, the ``mayan_settings`` folder
will be found inside the install Docker volume. If you installed Mayan EDMS
according to the :ref:`docker` instructions provided in this documentation
your ``mayan_settings`` folder should be located in the directory:
``/docker-volumes/mayan/mayan_settings``.
Create a file with any valid name and a ``.py`` extension in the
``mayan_settings`` folder. The file must starts with a global import of
``mayan.settings.production``. In the form::
from mayan.settings.production import *
Now add the corresponding lines to override the default settings.
In the settings file, it is not necessary to prepend the string ``MAYAN_`` to
the setting option. For example, to change the number of documents displayed
per page (COMMON_PAGINATE_BY, by default 40),
use::
COMMON_PAGINATE_BY=10
versus::
export MAYAN_COMMON_PAGINATE_BY=10
when using the environment variable method.
For this example let's assume the file was saved with the name ``mysettings.py``.
The way used to tell Mayan EDMS to import this file will vary based on the
installation method.
For the :ref:`deploying` method, the full import path will be
``mayan.media.mayan_settings.mysettings`` and can be passed via the
``--settings`` command line argument like this::
python manage.py runserver --settings=mayan.media.mayan_settings.mysettings
or via the ``DJANGO_SETTINGS_MODULE`` environment variable like this::
export DJANGO_SETTINGS_MODULE=mayan.media.mayan_settings.mysettings
For the :ref:`docker` installation method, the full import path will be
``mayan_settings.mysettings`` and can only be passed via the
``MAYAN_SETTINGS_MODULE`` environment variable like this::
docker run <...> -e MAYAN_SETTINGS_MODULE=mayan_settings.mysettings

6
docs/topics/signatures.rst → docs/chapters/signatures.rst
View File

@@ -1,6 +1,6 @@
===================
*******************
Document signatures
===================
*******************
Mayan EDMS supports two types of document signatures: embedded and
detached signatures. When a document with an embedded signature is
@@ -25,7 +25,7 @@ signatures sections of a document.
Signed documents are tamper-proof. That means that if any part of the document's
file is edited (even just one character or one pixel), the document's
signature becomes invalid alerting that an unathorized change has ocurred.
signature becomes invalid alerting that an unauthorized change has occurred.
Existing non signed documents can be signed in one of two ways:
by downloading the document, signing it, and uploading the signed document

1
docs/topics/smart_links.rst → docs/chapters/smart_links.rst
View File

@@ -1,4 +1,3 @@
===========
Smart links
===========

1
docs/topics/sources.rst → docs/chapters/sources.rst
View File

@@ -1,4 +1,3 @@
=======
Sources
=======

1
docs/topics/tags.rst → docs/chapters/tags.rst
View File

@@ -1,4 +1,3 @@
====
Tags
====

26
docs/topics/transformations.rst → docs/chapters/transformations.rst
View File

@@ -1,21 +1,21 @@
===============
***************
Transformations
===============
***************
Transformations are persistent manipulations to the previews of the stored
documents. For example: a scanning equipment may only produce landscape PDFs.
In this case a useful transformation for that document source would be to rotate
all scanned documents by 270 degrees after being uploaded. By adding this
transformation to the Mayan EDMS source that is connected to the scanner, all
pages scanned via that source will inherit the transformation as they are
created. The result is that whenever a document is uploaded from that scanner,
Transformations are persistent manipulations to the previews of the stored
documents. For example: a scanning equipment may only produce landscape PDFs.
In this case a useful transformation for that document source would be to rotate
all scanned documents by 270 degrees after being uploaded. By adding this
transformation to the Mayan EDMS source that is connected to the scanner, all
pages scanned via that source will inherit the transformation as they are
created. The result is that whenever a document is uploaded from that scanner,
it will appear in portrait orientation, instead of landscape orientation.
Transformations can also be added to existing documents by clicking on a
document's page and then clicking on "transformations". In this view the Actions
menu will have a new option that reads "Create new transformation". Currently,
the available transformations are: rotation, zoom, crop, and resize. Once the
document's page and then clicking on "transformations". In this view the Actions
menu will have a new option that reads "Create new transformation". Currently,
the available transformations are: rotation, zoom, crop, and resize. Once the
document image has been corrected, resubmit it for OCR for improved results.
Transformations are not destructive and do not physically modify the document
Transformations are not destructive and do not physically modify the document
file, they just modify the document's graphical representation.

4
docs/topics/translations.rst → docs/chapters/translations.rst
View File

@@ -1,6 +1,6 @@
============
************
Translations
============
************
Translations are handled online via the **Transifex** website:
https://www.transifex.com/projects/p/mayan-edms/. To create a translation team

4
docs/topics/upload_wizard.rst → docs/chapters/upload_wizard.rst
View File

@@ -1,6 +1,6 @@
=============
*************
Upload wizard
=============
*************
The steps needed to upgrade a document using form-tools' ``SessionWizard``
were hardcoded in the ``source`` app. This made it very difficult to add or remove

4
docs/topics/versioning.rst → docs/chapters/versioning.rst
View File

@@ -1,6 +1,6 @@
===================
*******************
Document versioning
===================
*******************
Mayan EDMS has the ability to store different versions of the same
document. A comment field is provided to allow users to summarize the new

32
docs/conf.py
View File

@@ -232,3 +232,35 @@ man_pages = [
]
html_theme = 'sphinx_rtd_theme'
from docutils import nodes, utils
from docutils.parsers.rst import roles
from sphinx.roles import _amp_re
def patched_menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
text = utils.unescape(text)
if typ == 'menuselection':
text = text.replace('-->', 'qwe\N{RIGHTWARDS ARROW}') # Here is the patch
spans = _amp_re.split(text)
node = nodes.emphasis(rawtext=rawtext)
for i, span in enumerate(spans):
span = span.replace('&&', '&')
if i == 0:
if len(span) > 0:
textnode = nodes.Text(span)
node += textnode
continue
accel_node = nodes.inline()
letter_node = nodes.Text(span[0])
accel_node += letter_node
accel_node['classes'].append('accelerator')
node += accel_node
textnode = nodes.Text(span[1:])
node += textnode
node['classes'].append(typ)
return [node], []
# Use 'patched_menusel_role' function for processing the 'menuselection' role
roles.register_local_role('menuselection', patched_menusel_role)

41
docs/index.rst
View File

@@ -17,43 +17,22 @@ repository for electronic documents.
.. toctree::
:hidden:
Installation <topics/installation>
Features <topics/features>
Installation <topics/installation>
Getting started <topics/getting_started>
Release notes and upgrading <releases/index>
ACLs <topics/acls>
Backups <topics/backups>
Checkouts <topics/checkouts>
Document types <topics/document_types>
File storage <topics/file_storage>
Document indexes <topics/indexes>
Document languages <topics/languages>
Document signatures <topics/signatures>
Mailing <topics/mailing>
Metadata <topics/metadata>
OCR <topics/ocr_backend>
Permissions <topics/permissions>
Access control <topics/access_control>
Categorization <topics/categorization>
Collaboration <topics/collaboration>
Settings <topics/settings>
Sources <topics/sources>
Smart links <topics/smart_links>
Tags <topics/tags>
Transformations <topics/transformations>
Upload wizard <topics/upload_wizard>
Versioning <topics/versioning>
Docker image <topics/docker>
Direct deployments <topics/deploying>
Scaling up <topics/scaling_up>
Storage <topics/storage>
Maintenance <topics/maintenance>
Advanced topics <topics/advanced>
Development <topics/development>
App creation <topics/app_creation>
Translations <topics/translations>
Licensing <topics/license>
FAQ <topics/faq>
Licensing <topics/license>
Contact <topics/contact>
MERCs <mercs/index>
Individual Contributor Assignment Agreement <topics/caa_individual>
Entity Contributor Assignment Agreement <topics/caa_entity>
.. _Docker: https://www.docker.com/
.. _Django: http://www.djangoproject.com/

3
docs/mercs/0001-merc-process.rst
View File

@@ -1,6 +1,5 @@
==============================
MERC 1: Purpose and Guidelines
==============================
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:MERC: 1
:Author: Michael Price

20
docs/mercs/0003-using-javascript-libraries.rst
View File

@@ -1,5 +1,5 @@
==================================
MERC 3: Using javascript libraries
MERC 3: Using JavaScript libraries
==================================
:MERC: 3
@@ -17,13 +17,13 @@ MERC 3: Using javascript libraries
Abstract
========
This MERC proposes a standard way to use javascript libraries.
This MERC proposes a standard way to use JavaScript libraries.
Rationale
=========
Mayan EDMS uses several javascript libraries for user interface features.
Currently, the libraries are not installed using any javascript package
Mayan EDMS uses several JavaScript libraries for user interface features.
Currently, the libraries are not installed using any JavaScript package
manager but copied uncompressed. Installing the libraries in this manner
carries some disadvantages.
@@ -32,7 +32,7 @@ Motivation
The inclusion of the libraries in source form is required by many licenses
if the library is not installed by a package manager in distributable form.
There are several disavantages with the current approach:
There are several disadvantages with the current approach:
1. Having the library in source form means that the entire weight of the
library's size carries over the overall size of the Mayan EDMS distribution files.
@@ -42,7 +42,7 @@ There are several disavantages with the current approach:
installed in the project and manually searching, downloading, compressing
and adding the files to the repository.
3. The source form of the libraries includes normal and minified versions
of the code and the accompaning CSS files. There is no define preference
of the code and the accompanying CSS files. There is no define preference
and through the project both versions of the libraries are loaded
interchangeably. Using a packager manager the minified version would be
used of a pipeline to minify the installed libraries should be added.
@@ -58,10 +58,10 @@ Specification
Changes needed:
1. Python based javascript package manager. Alternatively a Python wrapper
for a javascript package manager could be used.
2. Package manifest for the javascript libraries used.
3. Installation pipeline to install the javascript libraries during the
1. Python based JavaScript package manager. Alternatively a Python wrapper
for a JavaScript package manager could be used.
2. Package manifest for the JavaScript libraries used.
3. Installation pipeline to install the JavaScript libraries during the
installation and setup of the project.
References:

4
docs/mercs/0004-support-forum.rst
View File

@@ -42,5 +42,5 @@ issues regarding Google, reinforce the need for a self hosted solution.
Specification
=============
Platform choosen was phpBB. Factors were: written in PHP, ease of installation,
compatible with several database managers, mature, extersive development history.
Platform chosen was phpBB. Factors were: written in PHP, ease of installation,
compatible with several database managers, mature, extensive development history.

20
docs/mercs/index.rst
View File

@@ -1,6 +1,6 @@
=====
*****
MECRs
=====
*****
Mayan EDMS Request For Comment documents index.
@@ -17,9 +17,9 @@ Accepted
.. toctree::
:maxdepth: 1
0001-merc-process
0002-test-writing
0003-using-javascript-libraries
../mercs/0001-merc-process
../mercs/0002-test-writing
../mercs/0003-using-javascript-libraries
Draft
-----
@@ -27,7 +27,7 @@ Draft
.. toctree::
:maxdepth: 1
merging-roles-and-groups
../mercs/merging-roles-and-groups
Type
@@ -38,8 +38,8 @@ Process
.. toctree::
:maxdepth: 1
0001-merc-process
0004-support-forum
../mercs/0001-merc-process
../mercs/0004-support-forum
Feature
@@ -47,5 +47,5 @@ Feature
.. toctree::
:maxdepth: 1
0002-test-writing
0003-using-javascript-libraries
../mercs/0002-test-writing
../mercs/0003-using-javascript-libraries

4
docs/mercs/merging-roles-and-groups.rst
View File

@@ -30,7 +30,7 @@ overheads without providing advantages in the day to day operations.
In reality there is almost a 1 to 1 correlation between Roles and Groups.
Other permissions systems already use Groups as permission units without
disavantages. An example of this is LDAP and its commercial counterpart
disadvantages. An example of this is LDAP and its commercial counterpart
Active Directory.
Motivation
@@ -43,7 +43,7 @@ favor of using a native Django model for the same task.
Merging the Role and Group models will also provide a speed boost in every
permission check and queryset filtering. These checks are nested in nature.
Since the access checks are performed for every view and for every link
in the view the performace gain should be substantial.
in the view the performance gain should be substantial.
Backwards Compatibility
=======================

32
docs/releases/0.10.rst
View File

@@ -16,36 +16,36 @@ Version 0.10
* LibreOffice (https://www.libreoffice.org/)
* unoconv [version 0.5] (https://github.com/dagwieers/unoconv)
* The new office documents converter won't convert files with the extension
.docx because these files are recognized as zip files instead. This
* The new office documents converter won't convert files with the extension
.docx because these files are recognized as zip files instead. This
is an issue of the libmagic library.
* New configuration option added ``CONVERTER_UNOCONV_USE_PIPE`` that controls
how unoconv handles the communication with LibreOffice. The default of
``True`` causes unoconv to use **pipes**, this approach is slower than using
* New configuration option added ``CONVERTER_UNOCONV_USE_PIPE`` that controls
how unoconv handles the communication with LibreOffice. The default of
``True`` causes unoconv to use **pipes**, this approach is slower than using
**TCP/IP** ports but it is more stable.
* Initial `REST` `API` that exposes documents properties and one method, this
new `API` is used by the new smart document widget and requires the
* Initial `REST` `API` that exposes documents properties and one method, this
new `API` is used by the new smart document widget and requires the
package ``djangorestframework``, users must issue a::
$ pip install -r requirements/production.txt
to install this new requirement.
* MIME type detection and caching performance updates.
* Updated the included version of ``jQuery`` to 1.7
* Updated the included version of ``JqueryAsynchImageLoader`` to 0.9.7
* Document image serving response now specifies a MIME type for increased
* Document image serving response now specifies a MIME type for increased
browser compatibility.
* Small change in the scheduler that increases stability.
* Russian translation updates Sergey Glita
* Improved and generalized the OCR queue locking mechanism, this should
eliminate any posibility of race conditions between Mayan EDMS OCR nodes.
* Improved and generalized the OCR queue locking mechanism, this should
eliminate any possibility of race conditions between Mayan EDMS OCR nodes.
* Added support for signals to the OCR queue, this results in instant OCR
processing upon submittal of a document to the OCR queue, this works in
addition to the current polling processing which eliminates the
posibility of stale documents in the OCR queue.
possibility of stale documents in the OCR queue.
* Added multiple document OCR submit link
* Re enabled tesseract language specific OCR processing and added a one
* Re enabled Tesseract language specific OCR processing and added a one
(1) time language neutral retry for failed language specific OCR

2
docs/releases/0.12.rst
View File

@@ -26,7 +26,7 @@ releases:
* All app permissions have been move to a separate permissions.py file
per app
* Complete permission system refactor.
* Document signining code move to it's own app
* Document signing code moved to it's own app
* Initial unit tests
* A lot of logging used throught the entire project.
* Much functionality moved to model managers.

6
docs/releases/3.0.rst
View File

@@ -389,7 +389,7 @@ Other changes worth mentioning
- Unify all document widgets.
- Printed pages are now full width.
- Move the invalid document markup to a separate HTML template.
- Move transfomations to their own module.
- Move transformations to their own module.
- Split documents.tests.test_views into:
- base.py
@@ -408,7 +408,7 @@ Other changes worth mentioning
- Fix documentation formatting.
- Add upload wizard step documentation chapter.
- Improve and add additional diagrams.
- Change documenation theme to rtd.
- Change documentation theme to rtd.
- Add the "to=" keyword argument to all ForeignKey, ManayToMany and
OneToOne Fields.
- Rename the role groups link label from "Members" to "Groups".
@@ -511,7 +511,7 @@ Other changes worth mentioning
errors in production. Defaults to False.
- Change the error log file handle class to RotatingFileHandle to avoid an
indefinitely growing log file.
- Disable embedded signatute verification during the perform upgrade command.
- Disable embedded signature verification during the perform upgrade command.
- Replace the DOCUMENTS_LANGUAGE_CHOICES setting option. Replaced with the
new DOCUMENTS_LANGUAGE_CODES.
- Reduce default language code choice from 7800 to the top 100 spoken

6
docs/releases/3.1.rst
View File

@@ -120,7 +120,7 @@ be imported back using a different database engine. With this feature eases
the migration from SQLite to other database managers like PostgreSQL, MySQL or
MariaDB.
The export and import can be done using the dumpdata and loadata command or
The export and import can be done using the dumpdata and loaddata command or
the new command convertdb.
Changed settings
@@ -327,7 +327,7 @@ Other changes
- Update forum link in the about menu.
- Only show the settings namespace list link where it is
relevant.
- Use platform independant hashing for transformations.
- Use platform independent hashing for transformations.
- Add support to the ObjectActionMixin to report on instance action
failures. Add also an error_message class property and the new
ActionError exception.
@@ -366,7 +366,7 @@ Other changes
- Improve the speed of the document indexing.
- Move the matchHeight call from lazy loading to image loading.
Reduces the chance of wrongly sized cards.
- Generalize the Javascript menu rendering into an API for
- Generalize the JavaScript menu rendering into an API for
templates that only refresh the menu when there are changes.
Closes GitLab issue #511. Thanks to Daniel Carrico
@daniel1113 for the report.

40
docs/releases/index.rst
View File

@@ -1,6 +1,6 @@
=============
#############
Release notes
=============
#############
Release notes for the official Mayan EDMS releases. Each release note will tell you
what's new in each version, and will also describe any backwards-incompatible
@@ -11,14 +11,12 @@ all the backwards-incompatible changes and deprecated features for
each 'final' release from the one after your current Mayan EDMS version,
up to and including the latest version.
Final releases
==============
Below are release notes through Mayan EDMS |version| and its minor releases. Newer
versions of the documentation contain the release notes for any later releases.
**********
3.0 series
----------
**********
.. toctree::
:maxdepth: 1
@@ -36,8 +34,9 @@ versions of the documentation contain the release notes for any later releases.
3.0
**********
2.0 series
----------
**********
.. toctree::
:maxdepth: 1
@@ -72,8 +71,9 @@ versions of the documentation contain the release notes for any later releases.
2.0.1
2.0
**********
1.0 series
----------
**********
.. toctree::
:maxdepth: 1
@@ -81,15 +81,17 @@ versions of the documentation contain the release notes for any later releases.
1.1
1.0
************
0.13 release
------------
************
.. toctree::
:maxdepth: 1
0.13
************
0.12 release
------------
************
.. toctree::
:maxdepth: 1
@@ -97,32 +99,36 @@ versions of the documentation contain the release notes for any later releases.
0.12.1
0.12
************
0.11 release
------------
************
.. toctree::
:maxdepth: 1
0.11.1
0.11
************
0.10 release
------------
************
.. toctree::
:maxdepth: 1
0.10.1
0.10
***********
0.9 release
-----------
***********
.. toctree::
:maxdepth: 1
0.9.1
0.9
***********
0.8 release
-----------
***********
.. toctree::
:maxdepth: 1
@@ -131,8 +137,9 @@ versions of the documentation contain the release notes for any later releases.
0.8.1
0.8
***********
0.7 release
-----------
***********
.. toctree::
:maxdepth: 1
@@ -142,8 +149,9 @@ versions of the documentation contain the release notes for any later releases.
0.7.3
0.7
***********
0.5 release
-----------
***********
.. toctree::
:maxdepth: 1

181
docs/spelling_wordlist.txt
View File

@@ -1,70 +1,117 @@
MERC
Django
Tesseract
backend
minified
phpBB
Grappelli
unoconv
Sergey
Glita
fabfile
poppler
Transifex
pdftotext
frontend
Redis
backend
Kombu
filesystem
serializers
runtime
api
uncompress
Carrico
daniel
Urlichs
german
mixin
namespace
Postgres
mayan
makefile
backends
hostname
webserver
utf
Libre
Storages
filesystems
hardcoded
Gunicorn
GitLab
parsers
mountindex
compat
viewport
dropzone
convertdb
papercut
dumpdata
loaddata
Lokesh
lokesh
papercuts
schoeftner
adf
dropdown
django
unix
changelog
localhost
readonly
Paperattor
paperattor
jQuery
Teixeira
ajax
ajaxForm
api
ascii
Schöftner
robert
backend
backends
Backport
Carrico
changelog
codebase
compat
config
convertdb
cors
Customizable
daniel
dateutil
distributable
django
Django
docx
drf
dropdown
dropzone
dumpdata
entrypoint
fabfile
fancybox
farroq
Farroq
filesystem
filesystems
formtools
frontend
german
gevent
GitLab
Glita
Grappelli
gunicorn
Gunicorn
Hamish
hardcoded
hostname
init
Jesaja
jQuery
keyserver
keyservers
Kombu
libmagic
Libre
loaddata
localhost
lokesh
Lokesh
Ludmann
Maglana
makefile
matchHeight
mayan
MERC
minified
minify
mixin
mountindex
mptt
namespace
namespaces
noop
paperattor
Paperattor
papercut
papercuts
parsers
pdftotext
phpBB
poppler
Postgres
PyOCR
qsstats
queryset
querystring
readonly
readthedocs
Redis
relaxdiego
renderer
robert
runtime
schoeftner
Schöftner
Sergey
serializers
Storages
subclassing
sublicense
Teixeira
Tesseract
TheOneValen
Transifex
uncompress
unix
unoconv
URI
Urlichs
utf
viewport
waitForJQuery
webserver
Whitenoise
yasg
Memcached
ModelLock
reindexing
prepend

16
docs/topics/access_control.rst Normal file
View File

@@ -0,0 +1,16 @@
##############
Access control
##############
Mayan EDMS uses a role based permission system
(https://en.wikipedia.org/wiki/Role-based_access_control) that provides a
mechanism to control access to the contained documents and system functions.
The role access control system is divided into two main groups:
* Permission grants to roles for the entire system.
* ACLs (access control lists). These are permission granted to a role for a
specific object or group of objects.
.. include:: ../chapters/permissions.rst
.. include:: ../chapters/acls.rst

12
docs/topics/advanced.rst Normal file
View File

@@ -0,0 +1,12 @@
###############
Advanced topics
###############
.. include:: ../chapters/languages.rst
.. include:: ../chapters/signatures.rst
.. include:: ../chapters/metadata.rst
.. include:: ../chapters/ocr_backend.rst
.. include:: ../chapters/transformations.rst
.. include:: ../chapters/versioning.rst
.. include:: ../chapters/scaling_up.rst

24
docs/topics/categorization.rst Normal file
View File

@@ -0,0 +1,24 @@
##############
Categorization
##############
Mayan EDMS several ways to visual organize documents. Document categorization
allows showing users different views of document groups. These are divided
into ones requiring manual maintenance and others that are updated
automatically.
**************
Manual methods
**************
.. include:: ../chapters/cabinets.rst
.. include:: ../chapters/tags.rst
*****************
Automatic methods
*****************
.. include:: ../chapters/indexes.rst
.. include:: ../chapters/smart_links.rst

7
docs/topics/collaboration.rst Normal file
View File

@@ -0,0 +1,7 @@
#############
Collaboration
#############
.. include:: ../chapters/checkouts.rst
.. include:: ../chapters/mailing.rst

44
docs/topics/contact.rst
View File

@@ -1,39 +1,47 @@
=======
#######
Contact
=======
#######
***
FAQ
---
***
* Try the :doc:`FAQ <faq>` -- it's got answers to many common questions.
Mailing list
------------
*****
Forum
*****
Search for information in the `archives of the mayan-edms mailing list`_, or
`post a question`_. If you prefer news servers, use the gateway provided by
Gmane_.
Search for information or post a question, report or feature request at:
https://forum.mayan-edms.com.
Mayan EDMS community developers do their best to reply to basic questions.
Be sure to check the list archives as it may already containt the answers to
your questions.
Mayan EDMS developers do their best to reply to basic questions.
Be sure to use the search feature of the forum as some posts may already
contain the answers to your questions.
*******
Twitter
-------
*******
Mayan EDMS has an official Twitter account, `@mayanedms
<http://twitter.com/mayanedms>`_, which is used for announcements and occasional
related news tidbits.
<https://twitter.com/mayanedms>`_, which is used for announcements and occasional
related news.
****
Wiki
****
A community Wiki is also available for material that doesn't fit in the
document or is being created in a collaborative manner to be added to the
documentation. The Wiki URL is https://wiki.mayan-edms.com
*******************
Bugs/ticket tracker
-------------------
*******************
Report bugs with Mayan EDMS or search existing ones using GitLab's `ticket tracker`_.
.. _archives of the mayan-edms mailing list: http://groups.google.com/group/mayan-edms/
.. _post a question: http://groups.google.com/group/mayan-edms
.. _ticket tracker: https://gitlab.com/mayan-edms/mayan-edms/issues
.. _Gmane: http://news.gmane.org/gmane.comp.python.django.mayan-edms

479
docs/topics/development.rst
View File

@@ -1,467 +1,12 @@
.. _development:
Development
===========
Mayan EDMS is under active development, and contributions are welcome.
If you have a feature request, suggestion or bug report, please open a new
issue on the `GitLab issue tracker`_. To submit patches, please send a merge
request on GitLab_.
.. _GitLab: https://gitlab.com/mayan-edms/mayan-edms/
.. _`GitLab issue tracker`: https://gitlab.com/mayan-edms/mayan-edms/issues
Project philosophies
--------------------
How to think about Mayan EDMS when doing changes or adding new features;
why things are the way they are in Mayan EDMS:
- Functionality must be as market/sector independent as possible, code for the
95% of use cases.
- Each user must be able to configure and customize it to their needs after
install.
- Abstract as much as possible, each app must be an expert in just one thing,
for other things they should use the API/classes/functions of other apps.
- Assume as little as possible about anything outside the project
(hardware, OS, storage).
- Provide Python based abstraction so that a default install runs with a single
step.
- No hard dependencies on binaries unless there is no other choice.
- Provide “drivers” or switchable backends to allow users to fine tune the
installation.
- Call to binaries only when there is no other choice or the Python choices are
not viable/mature/efficient.
- Each app is as independent and self contained as possible. Exceptions, the
basic requirements: navigation, permissions, common, main.
- If an app is meant to be used by more than one other app, it should be as
generic as possible in regard to the project and another app will bridge the functionality.
- Example: since indexing (document_indexing) only applies to documents, the
app is specialized and depends on the documents app.
Coding conventions
------------------
Follow PEP8
~~~~~~~~~~~
Whenever possible, but don't obsess over things like line length:
.. code-block:: bash
$ flake8 --ignore=E501,E128,E122 |less
To perform automatic PEP8 checks, install flake8's git hook using:
.. code-block:: bash
$ flake8 --install-hook git
Imports
~~~~~~~
Import order should be:
- Standard Python modules
- Installed Python modules
- Core Django modules
- Installed Django modules
- Mayan EDMS modules
- Local imports
Example:
.. code-block:: bash
from __future__ import absolute_import
# Standard Python library
import base64
# 3rd party installed Python libraries
import requests
# Django core modules
from django.db.models import Q
from django.template.defaultfilters import slugify
from django.utils.translation import ugettext
from django.utils.translation import ugettext_lazy as _
# 3rd party installed Django libraries
from rest_framework import APIView
# Mayan apps
from metadata.classes import MetadataClass
# Local app imports (relative)
from .conf.settings import (
AVAILABLE_INDEXING_FUNCTIONS,
MAX_SUFFIX_COUNT, SLUGIFY_PATHS
)
from .exceptions import MaxSuffixCountReached
from .filesystem import (
fs_create_index_directory, fs_create_document_link,
fs_delete_document_link, fs_delete_index_directory,
assemble_suffixed_filename
)
from .models import Index, IndexInstanceNode, DocumentRenameCount
All local app module imports are in relative form. Local app module name is to
be referenced as little as possible, unless required by a specific feature,
trick, restriction (e.g., Runtime modification of the module's attributes).
Incorrect:
.. code-block:: bash
# documents app views.py model
from documents.models import Document
Correct:
.. code-block:: bash
# documents app views.py model
from .models import Document
Dependencies
~~~~~~~~~~~~
Mayan EDMS apps follow a hierarchical model of dependency. Apps import from
their parents or siblings, never from their children. Think plugins. A parent
app must never assume anything about a possible existing child app. The
documents app and the Document model are the basic entities; they must never
import anything else. The common and main apps are the base apps.
Variables
~~~~~~~~~
Naming of variables should follow a Major to Minor convention, usually
including the purpose of the variable as the first piece of the name, using
underscores as spaces. camelCase is not used in Mayan EDMS.
Examples:
Links:
.. code-block:: bash
link_document_page_transformation_list = ...
link_document_page_transformation_create = ...
link_document_page_transformation_edit = ...
link_document_page_transformation_delete = ...
Constants:
.. code-block:: bash
PERMISSION_SMART_LINK_VIEW = ...
PERMISSION_SMART_LINK_CREATE = ...
PERMISSION_SMART_LINK_DELETE = ...
PERMISSION_SMART_LINK_EDIT = ...
Classes:
.. code-block:: bash
class Document(models.Model):
class DocumentPage(models.Model):
class DocumentPageTransformation(models.Model):
class DocumentType(models.Model):
class DocumentTypeFilename(models.Model):
Strings
~~~~~~~
Quotation character used in Mayan EDMS for strings is the single quote.
Double quote is used for multiple line comments or HTML markup.
Migrations
~~~~~~~~~~
Migrations should do only one thing (eg: either create a table, move data to a
new table or remove an old table) to aid retrying on failure.
General
~~~~~~~
Code should appear in their modules in alphabetic order or in their order of
importance if it makes more sense for the specific application. This makes
visual scanning easier on modules with a large number of imports, views or
classes. Class methods that return a value should be pretended with a
``get_`` to differentiate from an object’s properties. When a variable refers
to a file it should be named as follows:
- filename: The file’s name and extension only.
- filepath: The entire path to the file including the filename.
- path: A path to a directory.
Flash messages should end with a period as applicable for the language.
Only exception is when the tail of the message contains an exceptions message
as passed directly from the exception object.
Source Control
--------------
Mayan EDMS source is controlled with Git_.
The project is publicly accessible, hosted and can be cloned from **GitLab** using::
$ git clone https://gitlab.com/mayan-edms/mayan-edms.git
Git branch structure
--------------------
Mayan EDMS follows a simplified model layout based on Vincent Driessen's
`Successful Git Branching Model`_ blog post.
``develop``
The "next release" branch, likely unstable.
``master``
Current production release (|version|).
``feature/``
Unfinished/unmerged feature.
``series/``
Released versions.
Each release is tagged separately.
When submitting patches, please place your code in its own ``feature/`` branch
prior to opening a Merge Request on GitLab_.
.. _Git: http://git-scm.org
.. _`Successful Git Branching Model`: http://nvie.com/posts/a-successful-git-branching-model/
Steps to deploy a development version
-------------------------------------
.. code-block:: bash
$ git clone https://gitlab.com/mayan-edms/mayan-edms.git
$ cd mayan-edms
$ git checkout development
$ virtualenv venv
$ source venv/bin/activate
$ pip install -r requirements.txt
$ ./manage.py initialsetup
$ ./manage.py runserver
Contributing changes
--------------------
Follow the latest contributing guidelines outlined here: https://gitlab.com/mayan-edms/mayan-edms/blob/master/CONTRIBUTING.md
Debugging
---------
Mayan EDMS makes extensive use of Django's new `logging capabilities`_.
By default debug logging for all apps is turned on. If you wish to customize
how logging is managed turn off automatic logging by setting
`COMMON_AUTO_LOGGING` to ``False`` and add the following lines to your
``settings/local.py`` file::
LOGGING = {
'version': 1,
'disable_existing_loggers': True,
'formatters': {
'verbose': {
'format': '%(levelname)s %(asctime)s %(name)s %(process)d %(thread)d %(message)s'
},
'intermediate': {
'format': '%(name)s <%(process)d> [%(levelname)s] "%(funcName)s() %(message)s"'
},
'simple': {
'format': '%(levelname)s %(message)s'
},
},
'handlers': {
'console':{
'level':'DEBUG',
'class':'logging.StreamHandler',
'formatter': 'intermediate'
}
},
'loggers': {
'documents': {
'handlers':['console'],
'propagate': True,
'level':'DEBUG',
},
'common': {
'handlers':['console'],
'propagate': True,
'level':'DEBUG',
},
}
}
Likewise, to see the debug output of the ``tags`` app, just add the following inside the ``loggers`` block::
'tags': {
'handlers':['console'],
'propagate': True,
'level':'DEBUG',
},
.. _`logging capabilities`: https://docs.djangoproject.com/en/dev/topics/logging
Documentation
-------------
The documentation is written in `reStructured Text`_ format, processed with
Sphinx_, and resides in the ``docs`` directory. In order to build it, you will
first need to install the documentation editing dependencies with::
$ pip install -r requirements/documentation.txt
Then, to build an HTML version of the documentation, run the following command
from the **docs** directory::
$ make docs-serve
The generated documentation can be viewed by browsing to http://127.0.0.1:8000
or by browsing to the ``docs/_build/html`` directory.
You can also generate the documentation in formats other than HTML. Consult the
Sphinx_ documentation for more details.
.. _`reStructured Text`: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx.pocoo.org
Installable package
-------------------
Source file package
~~~~~~~~~~~~~~~~~~~
This is the sequence of step used to produce an installable package:
1. Generate the packaged version (will produce dist/mayan-edms-x.y.z.tar.gz)::
$ make sdist
2. Do a test install::
$ cd /tmp
$ virtualenv venv
$ source venv/bin/activate
$ pip install <path of the Git repository>/dist/mayan-edms-x.y.z.tar.gz
$ mayan-edms.py initialsetup
$ mayan-edms.py runserver
Wheel package
~~~~~~~~~~~~~
1. Install the development requirements::
$ pip install -r requirements/development.txt
2. Create wheel package using the makefile::
$ make wheel
3. Do a test install::
$ cd /tmp
$ virtualenv venv
$ source venv/bin/activate
$ pip install <path of the Git repository>/dist/mayan_edms-x.y.z-py2-none-any.whl
$ mayan-edms.py initialsetup
$ mayan-edms.py runserver
Version numbering
~~~~~~~~~~~~~~~~~
Mayan EDMS uses the Semantic Versioning (http://semver.org/) method to choose
version numbers along with Python's PEP-0440 (https://www.python.org/dev/peps/pep-0440/)
to format them.
X.YaN # Alpha release
X.YbN # Beta release
X.YrcN # Release Candidate
X.Y # Final release
Release checklist
~~~~~~~~~~~~~~~~~
1. Check for missing migrations::
make check-missing-migrations
2. Synchronize translations::
make translations-pull
3. Compile translations::
make translations-compile
4. Write release notes.
5. Update changelog.
6. Scan the code with flake8 for simple style warnings.
7. Check README.rst format with::
python setup.py check -r -s
or with::
make check-readme
8. Bump version in `mayan/__init__.py`.
9. Bump version in `docker/version`.
10. Update requirements version in `setup.py` using:
::
make generate-setup
11. Build source package and test:
::
make test-sdist-via-docker-ubuntu
12. Build wheel package and test:
::
make test-wheel-via-docker-ubuntu
13. Tag version:
::
git tag -a vX.Y.Z -m "Version X.Y.Z"
14. Switch to the `releases` branch:
::
git checkout releases
15. Push tag upstream:
::
git push --tags
16. Push code to trigger builds:
::
git push
17. Build and upload a test release:
::
make release-test-via-docker-ubuntu
18. Build and upload a final release:
::
make release-via-docker-ubuntu
###############
Advanced topics
###############
.. include:: ../chapters/development.rst
.. include:: ../chapters/app_creation.rst
.. include:: ../chapters/upload_wizard.rst
.. include:: ../chapters/translations.rst
.. include:: ../mercs/index.rst
.. include:: ../chapters/caa_entity.rst
.. include:: ../chapters/caa_individual.rst

4
docs/topics/faq.rst
View File

@@ -1,6 +1,6 @@
===
###
FAQ
===
###
Frequently asked questions and solutions

8
docs/topics/features.rst
View File

@@ -1,13 +1,13 @@
========
########
Features
========
########
* :doc:`Document versioning <../topics/versioning>`.
* :doc:`Document versioning <../chapters/versioning>`.
* Store many versions of the same document, download or revert to a previous
version.
* :doc:`Electronic signature verification <../topics/signatures>`.
* :doc:`Electronic signature verification <../chapters/signatures>`.
* Check the authenticity of documents by verifying their embedded
cryptographic signatures or upload detached signatures for document

9
docs/topics/getting_started.rst Normal file
View File

@@ -0,0 +1,9 @@
###############
Getting started
###############
These are the basic concepts you need to understand to start using Mayan EDMS.
.. include:: ../chapters/document_types.rst
.. include:: ../chapters/sources.rst

18
docs/topics/installation.rst
View File

@@ -1,18 +1,23 @@
############
Installation
============
############
The easiest way to use Mayan EDMS is by using the official Docker_ image.
Make sure Docker is properly installed and working before attempting to install
Mayan EDMS.
Hardware requirements
---------------------
*****************************
Minimum hardware requirements
*****************************
- 2 Gigabytes of RAM (1 Gigabyte if OCR is turned off).
- Multiple core CPU (64 bit, faster than 1 GHz recommended).
- Unix-like operating system like Linux and OpenBSD. For other operating systems
user container technologies like Docker or virtual machines.
****************
Docker procedure
----------------
****************
Docker is a computer program that performs operating-system-level
virtualization also known as containerization. It allows independent
@@ -31,12 +36,13 @@ the Docker image for Mayan EDMS.
Docker image chapter: :ref:`docker`
*******************
Direct installation
-------------------
*******************
For users with knowledge of Python, Django, Ubuntu, and databases.
Deployments chapter: :ref:`deploying`
Deployments chapter: :ref:`development`
.. _Docker: https://www.docker.com/

19
docs/topics/languages.rst
View File

@@ -1,19 +0,0 @@
=========
Languages
=========
The list of languages choices in the language dropdown used for documents is
based on the current ISO 639 list. This list can be quite extensive. To reduce
the number of languages available use the settings ``DOCUMENTS_LANGUAGE_CODES``,
and set it to a nested list of abbreviations + languages names like::
DOCUMENTS_LANGUAGE_CODES = ('eng', 'spa')
The default language to appear on the dropdown can also be configured using::
DOCUMENTS_LANGUAGE = 'spa'
Use the correct ISO 639-3 language abbreviation (https://en.wikipedia.org/wiki/ISO_639)
as this code is used in several subsystems in Mayan EDMS such as the OCR app
to determine how to interpret the document.

7
docs/topics/license.rst
View File

@@ -1,6 +1,6 @@
=======
#######
License
=======
#######
Mayan EDMS is distributed under the `Apache 2.0 License`_.
The complete license terms are included below.
@@ -8,7 +8,8 @@ The complete license terms are included below.
.. _Apache 2.0 License: https://www.apache.org/licenses/LICENSE-2.0.txt
*************
License terms
=============
*************
.. include:: ../../LICENSE

17
docs/topics/mailing.rst
View File

@@ -1,17 +0,0 @@
=================
Mailing documents
=================
To be able to send documents via email from inside Mayan EDMS you need to add
and configure the following configuration variables in your
mayan/settings/local.py file::
EMAIL_HOST = 'smtp.gmail.com' # Or similar
EMAIL_PORT = 587
EMAIL_HOST_USER = '<your smtp username>'
EMAIL_HOST_PASSWORD = '<your smtp password>'
EMAIL_USE_TLS = True
"Mail is sent using the SMTP host and port specified in the EMAIL_HOST and EMAIL_PORT settings. The EMAIL_HOST_USER andEMAIL_HOST_PASSWORD settings, if set, are used to authenticate to the SMTP server, and the EMAIL_USE_TLS and EMAIL_USE_SSL settings control whether a secure connection is used."
For more details consult Django's documentation on the topic: https://docs.djangoproject.com/en/1.8/ref/settings/#email-host

6
docs/topics/maintenance.rst Normal file
View File

@@ -0,0 +1,6 @@
###########
Maintenance
###########
.. include:: ../chapters/backups.rst

78
docs/topics/settings.rst
View File

@@ -1,78 +1,6 @@
========
########
Settings
========
########
Mayan EDMS can be configure via environment variables or by setting files.
.. include:: ../chapters/settings.rst
Via environment variables
=========================
To use environment variables, lookup the name of the setting you want to
override in the "Settings" menu. The "Settings" menu is located inside the
"Setup" main menu. To pass a value via an environment variable append
``"MAYAN_"`` to the name of the settings option. For example, to change
the number of documents displayed per page (COMMON_PAGINATE_BY, by default 40),
use::
export MAYAN_COMMON_PAGINATE_BY=10
Restart Mayan EDMS and the new value will take effect. The "Settings" menu
can be used to verify if the overrided setting value is being interpreted
correctly.
Via settings files
==================
Another way to configure Mayan EDMS is via Python-style, settings files.
If Mayan EDMS was installed using the Python package a ``mayan_settings``
folder will created for this purpose. If you installed Mayan EDMS
according to the :ref:`deploying` instructions provided in this
documentation your ``mayan_settings`` folder should be located in the directory:
``/usr/share/mayan-edms/mayan/media/mayan_settings``.
If Mayan EDMS was installed using Docker, the ``mayan_settings`` folder
will be found inside the install Docker volume. If you installed Mayan EDMS
according to the :ref:`docker` instructions provided in this documentation
your ``mayan_settings`` folder should be located in the directory:
``/docker-volumes/mayan/mayan_settings``.
Create a file with any valid name and a ``.py`` extension in the
``mayan_settings`` folder. The file must starts with a global import of
``mayan.settings.production``. In the form::
from mayan.settings.production import *
Now add the corresponding lines to override the default settings.
In the settings file, it is not necesary to prepend the string ``MAYAN_`` to
the setting option. For example, to change the number of documents displayed
per page (COMMON_PAGINATE_BY, by default 40),
use::
COMMON_PAGINATE_BY=10
versus::
export MAYAN_COMMON_PAGINATE_BY=10
when using the environment variable method.
For this example let's assume the file was saved with the name ``mysettings.py``.
The way used to tell Mayan EDMS to import this file will vary based on the
installation method.
For the :ref:`deploying` method, the full import path will be
``mayan.media.mayan_settings.mysettings`` and can be passed via the
``--settings`` command line argument like this::
python manage.py runserver --settings=mayan.media.mayan_settings.mysettings
or via the ``DJANGO_SETTINGS_MODULE`` environment variable like this::
export DJANGO_SETTINGS_MODULE=mayan.media.mayan_settings.mysettings
For the :ref:`docker` installation method, the full import path will be
``mayan_settings.mysettings`` and can only be passed via the
``MAYAN_SETTINGS_MODULE`` environment variable like this::
docker run <...> -e MAYAN_SETTINGS_MODULE=mayan_settings.mysettings

10
docs/topics/storage.rst Normal file
View File

@@ -0,0 +1,10 @@
#######
Storage
#######
Mayan EDMS stores documents in their original file format only changing the
filename to avoid collision.
.. include:: ../chapters/file_storage.rst
.. include:: ../chapters/object_storage.rst