diff --git a/HISTORY.rst b/HISTORY.rst index 275f3d27bb..5901419689 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -1,4 +1,4 @@ -Next (2018-XX-XX) +Next (2018-03-19) ================= - Fix permission filtering when performing document page searching. - Fix cabinet detail view pagination. @@ -54,6 +54,10 @@ Next (2018-XX-XX) - Add new WizardStep class to decouple the wizard step configuration. - Add support for deregister upload wizard steps. - Add wizard step to insert the document being uploaded to a cabinet. +- Fix documentation formatting. +- Add upload wizard step chapte. +- Improve and add additional diagrams. +- Change documenation theme to rtd. 2.8 (2018-02-27) ================ diff --git a/docs/_static/logo_pyramid_only.png b/docs/_static/logo_pyramid_only.png deleted file mode 100644 index 4a09190392..0000000000 Binary files a/docs/_static/logo_pyramid_only.png and /dev/null differ diff --git a/docs/_static/mayan-pyramid.svg b/docs/_static/mayan-pyramid.svg new file mode 100644 index 0000000000..648829dcff --- /dev/null +++ b/docs/_static/mayan-pyramid.svg @@ -0,0 +1,114 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/mayan_logo.png b/docs/_static/mayan_logo.png deleted file mode 100644 index 28f0bbb006..0000000000 Binary files a/docs/_static/mayan_logo.png and /dev/null differ diff --git a/docs/conf.py b/docs/conf.py index 19e9d860e1..f88fad3f56 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,7 +33,7 @@ sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext")) # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. #extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode'] #extensions = ["djangodocs", "sphinx.ext.intersphinx"] -extensions = ['djangodocs', 'sphinxcontrib.blockdiag'] +extensions = ['sphinxcontrib.blockdiag'] blockdiag_antialias = True blockdiag_html_image_format = "SVG" @@ -224,28 +224,8 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'mayanedms', 'Mayan EDMS Documentation', + ('index', 'mayanedms', '{} Documentation'.format(mayan.__title__), [mayan.__author__], 1) ] - -# -- Custom options -import alabaster - -html_theme_path = [alabaster.get_path()] -extensions.append('alabaster') -html_theme = 'alabaster' -html_sidebars = { - '**': [ - 'about.html', 'donate.html', 'navigation.html', 'searchbox.html', - ] -} -html_theme_options = { - 'description': mayan.__description__, - 'github_button': False, - 'travis_button': False, - 'gratipay_user': 'rosarior', - 'github_banner': False, -} - -html_logo = '_static/logo_pyramid_only.png' +html_theme = 'sphinx_rtd_theme' diff --git a/docs/index.rst b/docs/index.rst index b4acfd2daf..8fda4edbcd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,14 @@ -Welcome to Mayan EDMS! -====================== +Welcome to Mayan EDMS NG! +========================= + +Mayan EDMS NG is a modern fork of Mayan EDMS focused on stability, +perfomance and new features. + +.. image:: /_static/mayan-pyramid.svg + :alt: Icons made by Freepik (http://www.freepik.com) from www.flaticon.com is licensed by CC 3.0 BY (http://creativecommons.org/licenses/by/3.0/) + :align: center + :width: 30% + Mayan EDMS is a `Free Open Source`_ `Electronic Document Management System`_, coded in the Python language using the Django_ web application framework and @@ -26,6 +35,7 @@ repository for electronic documents. FAQ Contact MERCs + Pending tasks .. _Docker: https://www.docker.com/ .. _Django: http://www.djangoproject.com/ diff --git a/docs/mercs/merging-roles-and-groups.rst b/docs/mercs/merging-roles-and-groups.rst index c6bfe0e85d..874c944ee6 100644 --- a/docs/mercs/merging-roles-and-groups.rst +++ b/docs/mercs/merging-roles-and-groups.rst @@ -57,11 +57,11 @@ Specification Changes needed: -1- Data migration to convert existing roles to groups. -2- Prepend or append an identifier to the migrated roles. -3- Intermediate model to map permissions to a group. This will substitute +1. Data migration to convert existing roles to groups. +2. Prepend or append an identifier to the migrated roles. +3. Intermediate model to map permissions to a group. This will substitute the Role model's permissions many to many field. -4- Update the ``AccessControlList`` models roles field to point to the group +4. Update the ``AccessControlList`` models roles field to point to the group models. -5- Update the role checks in the ``check_access`` and ``filter_by_access`` +5. Update the role checks in the ``check_access`` and ``filter_by_access`` ``AccessControlList`` model manager methods. diff --git a/docs/mercs/using-javascript-libraries.rst b/docs/mercs/using-javascript-libraries.rst index 3835146dc0..afdcf90fa6 100644 --- a/docs/mercs/using-javascript-libraries.rst +++ b/docs/mercs/using-javascript-libraries.rst @@ -58,13 +58,14 @@ Specification Changes needed: -1- Python based javascript package manager. Alternatively a Python wrapper +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 +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: + - https://github.com/JDeuce/powser - https://github.com/javrasya/version-manager - https://github.com/inveniosoftware-attic/setuptools-bower diff --git a/docs/releases/2.5.1.rst b/docs/releases/2.5.1.rst index 0b1af58a4d..b1e25506c9 100644 --- a/docs/releases/2.5.1.rst +++ b/docs/releases/2.5.1.rst @@ -63,8 +63,6 @@ Backward incompatible changes Bugs fixed or issues closed =========================== -* None -======= * `GitLab issue #378 `_ Add metadata widget changes from @Macrobb * `GitLab issue #379 `_ Add new document version list view permission. diff --git a/docs/releases/3.0.rst b/docs/releases/3.0.rst new file mode 100644 index 0000000000..890bc2f370 --- /dev/null +++ b/docs/releases/3.0.rst @@ -0,0 +1,439 @@ +================================ +Mayan EDMS NG v3.0 release notes +================================ + +Released: March 19, 2018 + +What's new +========== + +Turning Mayan EDMS into a single page app +----------------------------------------- +Historically, Mayan EDMS has steered away from adding too much Javascript +in its code. Roberto, the main developer, often explains his rationale +for this decision. His goal has been to maintain a robust, backend-based +page rendering method that will be as future-proof as possible. +This approach comes at the cost of some page loading speed, and reduced +user interface interactivity. + +The Javascript ecosystem is an untamed jungle of competing “standards”. +Between JQuery, Angular, React, Ember, CoffeeScript, ES2015, ES2017, +Babel, Grunt, Gulp, Bower, Webpack, Vue, Webpack, Rollup, Parcel, +among many others, is easy to see why that approach was the correct +one at the time. Luckily things have improved thanks to HTML5 and CCS3. +The browser can now do many things that often required convoluted +Javascript code to achieve. + +One of the most common complains about the user interface is that it +is slow, heavy, requires users to move around too much. That it +requires “too many clicks” to achieve things. + +Single Page Applications (SPAs) rewrite the current page dynamically +rather than loading the entire page on each click of the mouse. This +makes the web application feel and behave more like a desktop +application. Because the majority of the styling and Javascript code +is loaded only once, there is also the added benefit of less data down +the wire. Thus the application becomes lighter and provides a faster +response time to user events. Because the style is loaded and +interpreted at the beginning, the browser is also able to apply it to +the new content faster. + +In order to strike a balance with Roberto’s backend heavy philosophy, +we stuck to using just HTML5 and jQuery. Aside from two additional +jQuery libraries, there are no extra framework dependencies. With the +conversion to an SPA, many other petitions for user interface +improvements are now possible. We will work on these once the community +confirms that all the user interface changes made to create the SPA are +working as expected. + + +Upgrading to Django 1.11 +------------------------ +The move to Django 1.11 proved to be a real challenge. Even though +Django 1.11 is a minor release, it breaks compatibility and interfaces +in several key areas. Among these were templates and form widgets. + +Mayan EDMS uses a complex template, form and widget system. The system +mimics object-oriented concepts like inheritance at the rendering stage. +This allows the more than 300 views to be serviced with just a handful +of forms classes and base templates. Testing and auditing all the views +and forms after the upgrade was a lot of work. If any member of the +Django project is reading this, please adopt stricter version numbering +convention, something like Semantic Versioning. + +Along with the upgrade to Django 1.11, we fixed many deprecations +warning in preparation for an eventual upgrade to Django 2.0. + + +Notification improvements +------------------------- +In version 2.8 we introduced event notifications. These work by allowing +users to subscribe to a particular event like Document Uploads or to an +event of a particular document like when an invoice is edited. If +these events occur, the user gets a reminder next to the bell icon in +the main menu bar. This feature had one important limitation. The +notification reminder would only update if the main page updated. That +meant that if the user didn’t interact with the user interface they +would not get a notification reminder. + +We implemented a simple mechanism that checks for notifications +periodically without user intervention. We avoided the use of webworkers, +websockets and push notifications. The result is almost instant +notifications without user interaction and without adding any extra +dependencies. + + +Notification improvements +------------------------- +In version 2.8 we introduced event notifications. These work by allowing +users to subscribe to a particular event like Document Uploads or to an +event of a particular document like when an invoice is edited. If these +events occur, the user gets a reminder next to the bell icon in the main +menu bar. This feature had one important limitation. The notification +reminder would only update if the main page updated. That meant that if +the user didn’t interact with the user interface they would not get a +notification reminder. + +We implemented a simple mechanism that checks for notifications +periodically without user intervention. We avoided the use of webworkers, +websockets and push notifications. The result is almost instant +notifications without user interaction and without adding any extra +dependencies. + + +Migration squashing +------------------- +Database base migrations are a must to ensure your data remains coherent +after each upgrade. They need to be committed sequentially to simulate +the evolution of the database structures over time. This is true even +for new installations with no existing data. As Mayan EDMS matures and +adds features it also adds migrations. Each of these migration add up +to the amount of times it takes to install Mayan EDMS. + +Django recently added support for merging migrations. Because migrations +are sometimes interdependencies between each other, this is a delicate +procedure. Instead of getting wild with merges, we used the feature in +moderation. We merged the migrations that have proven to be stable over +the course of months or years. Additionally, these merged or “squashed” +migrations are only used for new installations. Any upgrade of an +existing installation will use the normal migrations. After some time, +if not issues are reported with the merged migrations, the individual +migrations will be removed and the merged migrations will take their place. + +These are the apps for which migrations were merged: + +- acls (ACLs): 1 and 2 +- checkouts (Checkouts): 1 and 2 +- common (Not shown in UI): 1 to 8 +- converter (Not shown in UI): from 1 to 12 +- django_gpg (Keys): from 1 to 6 +- document_indexing (Indexing): from 1 to 5 +- document_parsing (Parsing, “Content”): 1 and 2 +- document_signatures (Signatures): from 1 to 6 +- document_states (Workflows): 1 and 2 +- dynamic_search (Search): from 1 to 3 +- events (Event): from 1 to 4 +- linking (Smart links): from 1 to 5 +- lock_manager (Not shown in UI): 1 and 2 +- mailer (Mailing): from 1 to 5 +- metadata (Metadata): from 1 to 8 +- motd (Message of the day): from 1 to 5 +- permissions (Permissions): from 1 to 3 +- sources (Sources): from 1 to 16 + + +Dependencies upgrades +--------------------- +Most of the requirements, dependencies and libraries were upgraded to +their latest release. + +- Pillow: 5.0.0 +- django-activity-stream: 0.6.5 +- django-compressor: 2.2 +- django-cors-headers: 2.2.0 +- django-formtools: 2.1 +- django-qsstats-magic: 1.0.0 +- django-stronghold: 0.3.0 +- django-suit: 0.2.26 +- furl: 1.0.1 +- graphviz: 0.8.2 +- pyocr: 0.5.1 +- python-dateutil: 2.6.1 +- python-magic: 0.4.15 +- pytz: 2018.3 +- sh: 1.12.14 +- rest_framework_swagger replaced with drf-yasg: 1.5.0 +- FancyBox was upgraded to version 3, Font Awesome to version 5, jQuery to version 3.3.1. ajaxForm version 4.2.2, URI.js 1.19.1 and pace 0.7.8 were added as part of the conversion to single page app. + + +Search syntax +------------- +Searching without using a specialized search database is difficult. +Most software just take the lazy route and force the user to install a +dedicated search engine. Early on we noticed Mayan’s design called for +avoiding a separate search engine at the cost of some missing search +syntax. The OR and the negative term support is our first attempt at +adding special syntax to Mayan’s search code. If we get good feedback, +we plan to add more. + +By default now, search terms are routed to an “AND” query. That means +that a search for: + +``Tag1 Tag2`` + +will only return documents with both tags attached. To offer the +opposite choice we added an “OR” syntax. Searching for: + +``Tag1 OR Tag2`` + +will return documents with either tag attached. + +We also added support for literals terms. + +Searching for: + +``blue car`` + +will return documents with the words “blue” and “car”, even if they are +not together. That means getting documents with the phrases “blue sky” +and “slow car”. To search for exact terms enclose them in quotes: + +``“blue car”`` + +This will return only documents with the exact phrase “blue car”. + + +Running multiple instances of Mayan EDMS NG +------------------------------------------- +If you've ever tried running two instances of Mayan EDMS NG, you would +have noticed that they both try to create a lock file in the /tmp +directory with the same name. Only the first instance will be able to run. + +The lock filename needs to be unique to each instance, yet predictable +so that the workers of an instance can also access the same lock file. + +We solved this issues by using a hexadecimal hash representation of the +installation’s unique SECRET_KEY setting. The use of a hash makes +reversing the value in order to obtain the SECRET_KEY impossible for +all practical purposes. + + +Display resolution settings +--------------------------- +During the template work required to upgrade the version of Django, we +noticed that display sizes (display, preview, thumbnail) were specified +as a string that included the horizontal and the vertical resolution +separated by the character “x”. Using an “x” character to separate +resolution elements is not standard and didn't felt as well planned as +the rest of the project. The converter in Mayan EDMS NG also allows +specifying only the horizontal resolution. This design created some +ambiguities in the code. We decided to split the settings for specifying +resolutions into two settings for each size. One setting for +horizontal resolution and another for vertical resolution. + +The settings are now: + +``DOCUMENTS_DISPLAY_WIDTH``, ``DOCUMENTS_DISPLAY_HEIGHT``, ``DOCUMENTS_PREVIEW_WIDTH``, +``DOCUMENTS_PREVIEW_HEIGHT``, ``DOCUMENTS_PRINT_WIDTH``, ``DOCUMENTS_PRINT_HEIGHT``, +``DOCUMENTS_THUMBNAIL_WIDTH``, ``DOCUMENTS_THUMBNAIL_HEIGHT`` + + +Dynamic upload wizard steps +--------------------------- +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 +wizard steps. + +The steps of the wizard are now defined by a new class called +``sources.wizard.WizardStep``. The existing steps to select a document type, +enter metadata and tag the document, have been converted to function as +WizardSteps subclasses. The converted steps now live in + +``sources.wizards.WizardStepDocumentType``, ``tag.wizard_steps.WizardStepTags``, +and ``metadata.wizard_steps.WizardStepMetadata``. + +The steps need to define the following methods: + +- ``done``: This method is execute when the wizard finished the last step + an enter the step where the actual file are uploaded. This steps is used + to encode form data into the URL query string that will be passed to the + document upload view for each file uploaded. + +- ``condition``: This method is used to display the step conditionally. + If this method return True it will be displayed during the upload wizard + execution. To skip the step, return False or None. + +- ``get_form_initial``: This method is used to return the initial data + for the step form. Use this method to set up initial values for the step's + form fields. + +- ``step_post_upload_process``: This method will be executed once the + document finishes uploading. Use this method to process the information + encoded in the URL querystring by the step's `done`` method. + +Once the ``WizardStep`` subclass is defined, it needs to be registered. This +is done by calling the ``.register`` method of the ``WizardStep`` class with +the subclass as the argument. Example:: + + WizardStep.register(WizardStepMetadata) + +This statement must be located after the subclass definition. Finally, +the module defining the wizard step must be imported so that it is loaded +with the rest of the code and enabled. The best place to do this is in the +``.ready`` method of the apps' ``apps.py`` module. Example:: + + class TagsApp(MayanAppConfig): + has_rest_api = True + has_tests = True + name = 'tags' + verbose_name = _('Tags') + + def ready(self): + super(TagsApp, self).ready() + from actstream import registry + + from .wizard_steps import WizardStepTags # NOQA + +The WizardStep class also allows for unregistering existing steps. This +is accomplished by calling the ``.deregister`` method of the ``WizardStep`` +class and passing the subclass as the argument. This method should +also be called inside the ``.ready`` method of an apps' ``apps.py`` +module. Example:: + + + class TagsApp(MayanAppConfig): + has_rest_api = True + has_tests = True + name = 'tags' + verbose_name = _('Tags') + + def ready(self): + super(TagsApp, self).ready() + from actstream import registry + + from metadata.wizard_steps import WizardStepMetadata # NOQA + from sources.wizards import WizardStep # NOQA + from .wizard_steps import WizardStepTags # NOQA + + WizardStep.deregister(WizardStepTags) + + +This will cause the tags assigment step to not be assigned to the upload +wizard anymore. + + +Repository location +------------------- +The code repository for Mayan EDMS NG now lives at: +https://gitlab.com/Mayan-EDMS-NG/mayan-edms-ng + +A GitLab group was also created and all projects will now live under +that unit. + + +New upload step +--------------- +Using the new ``WizardStep`` class a new upload wizard step was added +to assign documents being uploaded to any number of cabinets while +being uploaded. This step was been assigned number 4 in the order of +step for uploading a file. + + +Other changes worth mentioning +------------------------------ +- Fix permission filtering when performing document page searching +- base.js was splitted into mayan_app.js, mayan_image.js, and partial_navigation.js. +- Cabinet detail view pagination was fixed. +- Improve permission handling in the workflow app. +- The checkedout detail view permission is now required for the checked out document detail API view. +- Add missing services for the checkout API. +- Fix existing checkout APIs. +- Update API views and serializers for the latest Django REST framework version. +- Update to the latest version the packages for building, development, documentation and testing. +- Add statistics script to produce a report of the views, APIs and test for each app. +- Merge base64 filename patch from Cornelius Ludmann. +- SearchModel return interface changed. The class no longer returns the result_set value. Use the queryset returned instead. +- Remove the unused scrollable_content internal feature. +- Remove unused animate.css package. +- Add the MERC specifying javascript library usage. +- Documents without at least a version are not scanned for duplicates. +- Convert document thumbnails, preview, image preview and staging files to template base widgets. +- 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. +- Split documents.tests.test_views into: + + - base.py + - test_deleted_document_views.py + - test_document_page_views.py + - test_document_type_views.py + - test_document_version_views.py + - test_document_views.py + - test_duplicated_document_views.py + +- Sort smart links by label. +- Rename the internal name of the document type permissions namespace. Existing permissions will need to be updated. +- Removed redundant permissions checks. + + +Removals +-------- +* None + + +Upgrading from a previous version +--------------------------------- + + +Using PIP +~~~~~~~~~ + +Type in the console:: + + $ pip install mayan-edms-ng==3.0 + +the requirements will also be updated automatically. + + +Using Git +~~~~~~~~~ + +If you installed Mayan EDMS by cloning the Git repository issue the commands:: + + $ git reset --hard HEAD + $ git pull + +otherwise download the compressed archived and uncompress it overriding the +existing installation. + +Next upgrade/add the new requirements:: + + $ pip install --upgrade -r requirements.txt + + +Common steps +~~~~~~~~~~~~ + +Migrate existing database schema with:: + + $ mayan-edms.py performupgrade + +Add new static media:: + + $ mayan-edms.py collectstatic --noinput + +The upgrade procedure is now complete. + + +Backward incompatible changes +============================= + +* None + +Bugs fixed or issues closed +=========================== + +* None + +.. _PyPI: https://pypi.python.org/pypi/mayan-edms/ diff --git a/docs/releases/index.rst b/docs/releases/index.rst index d462ab7ba0..195e956391 100644 --- a/docs/releases/index.rst +++ b/docs/releases/index.rst @@ -17,11 +17,20 @@ 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 + + 3.0 + + 2.0 series ---------- .. toctree:: :maxdepth: 1 + 2.8 2.7.3 2.7.2 2.7.1 diff --git a/docs/topics/acls.rst b/docs/topics/acls.rst index 0e6dd26d0f..94539ecf53 100644 --- a/docs/topics/acls.rst +++ b/docs/topics/acls.rst @@ -11,11 +11,13 @@ system-wide. .. blockdiag:: blockdiag { + default_shape = roundedbox + document [ label = 'Document' ]; role [ label = 'Role' ]; permission [ label = 'Permission' ]; - role -> document <- permission; + role -> permission -> document; } Example: @@ -23,11 +25,13 @@ Example: .. blockdiag:: blockdiag { + default_shape = roundedbox + document [ label = '2015 Payroll report.txt', width=200 ]; role [ label = 'Accountants' ]; permission [ label = 'View document' ]; - role -> document <- permission; + role -> permission -> document; } In this scenario only users in groups belonging to the ``Accountants`` role @@ -43,11 +47,14 @@ permission for all documents of that type. .. blockdiag:: blockdiag { + default_shape = roundedbox document_type [ label = 'Document type' ]; role [ label = 'Role' ]; permission [ label = 'Permission' ]; + documents [shape = "note", stacked]; - role -> document_type <- permission; + role -> permission -> document_type ; + document_type -> documents [folded, label = "inherit" ]; } Example: @@ -55,11 +62,14 @@ Example: .. blockdiag:: blockdiag { + default_shape = roundedbox document_type [ label = 'Payroll reports', width=200 ]; role [ label = 'Accountants' ]; permission [ label = 'View document' ]; + documents [shape = "note", stacked, label="payroll_report*.pdf" ]; - role -> document_type <- permission; + role -> permission -> document_type ; + document_type -> documents [folded, label = "inherit" ]; } The role ``Accountants`` is given the permission ``document view`` for the diff --git a/docs/topics/document_types.rst b/docs/topics/document_types.rst index f5d8b9893b..7ee5d40675 100644 --- a/docs/topics/document_types.rst +++ b/docs/topics/document_types.rst @@ -9,6 +9,46 @@ uploaded. It is not possible to upload documents without assigning them a document type. Examples of document type: **invoices**, **blueprints**, **receipts**. +.. blockdiag:: + + blockdiag { + default_shape = roundedbox + + document_type [ label = 'Document type' ]; + documents [ label = 'Documents' ]; + + document_type -> documents; + } + + +Examples: + +.. blockdiag:: + + blockdiag { + default_shape = roundedbox + + document_type [ label = 'Invoice' ]; + documents_1 [ label = 'invoice_001.pdf', width=200 ]; + documents_2 [ label = 'invoice_032.pdf', width=200 ]; + + document_type -> documents_1, documents_2; + } + + +.. blockdiag:: + + blockdiag { + default_shape = roundedbox + + document_type [ label = 'Receipts' ]; + documents_1 [ label = 'groceries_18-01-11.pdf', width=200 ]; + documents_2 [ label = 'car_payment-17-01-02.png', width=200 ]; + + document_type -> documents_1, documents_2; + } + + Settings and attributes are applied to document types and documents will inherit those settings and attributes based on the document type they were assigned when uploaded into Mayan EDMS. A document can only be of one diff --git a/docs/topics/file_storage.rst b/docs/topics/file_storage.rst index ed39309c3e..56efab30fe 100644 --- a/docs/topics/file_storage.rst +++ b/docs/topics/file_storage.rst @@ -9,6 +9,7 @@ without extension, and stored in a simple flat arrangement in a directory. .. blockdiag:: blockdiag { + default_shape = roundedbox file [ label = 'mayan_1-1.pdf', width=120]; document [ label = 'mayan/media/document_storage/ab6c1cfe-8a8f-4a30-96c9-f54f606b9248', width=450]; file -> document [label = "upload"]; diff --git a/docs/topics/index.rst b/docs/topics/index.rst index c56f987808..cc0d05abd4 100644 --- a/docs/topics/index.rst +++ b/docs/topics/index.rst @@ -24,5 +24,6 @@ Introductions to all the key parts of Mayan EDMS you'll need to know: settings file_storage backups + upload_wizard pending_work code_statistics diff --git a/docs/topics/indexes.rst b/docs/topics/indexes.rst index 8990fa6064..3898544c6f 100644 --- a/docs/topics/indexes.rst +++ b/docs/topics/indexes.rst @@ -23,6 +23,9 @@ Example: .. 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]; @@ -50,6 +53,8 @@ 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 ]; @@ -89,5 +94,20 @@ via the network with network file system software like `Samba `_ or `NFS `_. +.. 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. diff --git a/docs/topics/installation.rst b/docs/topics/installation.rst index e831bae59e..42a8561cea 100644 --- a/docs/topics/installation.rst +++ b/docs/topics/installation.rst @@ -16,7 +16,7 @@ Docker procedure For the complete set of installation, configuration, upgrade, and backup instructions visit the Mayan EDMS Docker Hub page at: -https://hub.docker.com/r/mayanedms/mayanedms/ +https://hub.docker.com/r/mayanedmsng/mayanedmsng/ .. _Docker: https://www.docker.com/ diff --git a/docs/topics/pending_work.rst b/docs/topics/pending_work.rst index 7aaa84a3e2..1e77a9911c 100644 --- a/docs/topics/pending_work.rst +++ b/docs/topics/pending_work.rst @@ -279,7 +279,7 @@ Other relationship between the documents has to be designed. - Manually linking documents. - Migrate settings/base.py to Django's 1.11 format. -- Rename model methods to use 'get_' or 'do_' +- Rename model methods to use ``get_`` or ``do_`` - Hunt TODO - Hunt FIXME - Convert SETTING_GPG_BACKEND into a setting option similar to converter and converter options. diff --git a/docs/topics/permissions.rst b/docs/topics/permissions.rst index 5162484836..7808b42419 100644 --- a/docs/topics/permissions.rst +++ b/docs/topics/permissions.rst @@ -10,6 +10,11 @@ that permission can exercise it throughout the entire system. .. blockdiag:: blockdiag { + orientation = portrait + default_shape = roundedbox + span_width = 240; + span_height = 100; + user [ label = 'Users' ]; group [ label = 'Groups' ]; role [ label = 'Roles' ]; diff --git a/docs/topics/settings.rst b/docs/topics/settings.rst index a5a9955b4a..17e1e89c97 100644 --- a/docs/topics/settings.rst +++ b/docs/topics/settings.rst @@ -12,7 +12,7 @@ your browser. This is also a good place to check if your overrided setting option value in your ``local.py`` file is being interpreted correctly. Settings can also be changed via environment variables by prepending the string -"MAYAN_" to the configuration name. For example, to change the number of documents +``"MAYAN_"`` to the configuration name. For example, to change the number of documents displayed per page (COMMON_PAGINATE_BY, by default 40), use:: MAYAN_COMMON_PAGINATE_BY=10 diff --git a/docs/topics/signatures.rst b/docs/topics/signatures.rst index f9efcc1e18..105f5b30a8 100644 --- a/docs/topics/signatures.rst +++ b/docs/topics/signatures.rst @@ -8,6 +8,25 @@ uploaded, this signature is readily detected as part of the document inspection step. The status of the signature can be verified by accessing the signatures sections of a document. +.. blockdiag:: + + blockdiag { + orientation = portrait + span_width = 240; + + user [ shape = "actor" ]; + key [ shape = flowchart.database, label = "Key" ]; + document [ shape = "note", label = "Document" ]; + document_signed [ label = "Signed\nDocument" ]; + + + key -> user -> document -> document_signed; + } + +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. + Existing non signed documents can be signed in one of two ways: by downloading the document, signing it, and uploading the signed document as a new version of the existing one or by creating a detached signature for @@ -21,6 +40,6 @@ keys no longer needed can also be deleted from this menu. Only `GNU Privacy Guard`_ signatures are support at the moment. -Only version 1 of `GNU Privacy Guard`_ is supported for now. +Only version 1 of `GNU Privacy Guard`_ is supported at the moment. .. _`GNU Privacy Guard`: www.gnupg.org/ diff --git a/docs/topics/sources.rst b/docs/topics/sources.rst index b4e720d366..e38f576c6e 100644 --- a/docs/topics/sources.rst +++ b/docs/topics/sources.rst @@ -31,6 +31,27 @@ The current document sources supported are: when the quality of the scans is irrelevant or when they will be known to be of good quality, such as when receiving e-faxes as PDFs. +.. blockdiag:: + + blockdiag { + mayan [shape = "roundedbox", label = "Mayan EDMS" ]; + email_pop3 [shape = "mail", label = "e-mail (POP3)"]; + email_imap [shape = "mail", label = "e-mail (IMAP)"]; + staging [shape = "flowchart.database", label = "Staging folder" ]; + watch [shape = "flowchart.database", label = "Watch folder" ]; + automatic [shape = "box", label = "Automatic\n(via schedule)" ]; + manual [shape = "actor", height=60, label = "Manual\n(user interaction)" ]; + web [shape = "note", label = "Webform upload" ]; + + automatic -> mayan; + email_pop3 -> automatic; + email_imap -> automatic; + watch -> automatic; + manual -> mayan; + staging -> manual; + web -> manual; + } + Document source can be configure to allow document bundles to uploaded as compressed files which are decompressed and their content uploaded as separate documents. This feature is useful when migrating from another document diff --git a/docs/topics/upload_wizard.rst b/docs/topics/upload_wizard.rst new file mode 100644 index 0000000000..32a268aee7 --- /dev/null +++ b/docs/topics/upload_wizard.rst @@ -0,0 +1,84 @@ +============= +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 +wizard steps. + +The steps of the wizard are now defined by a new class called +``sources.wizard.WizardStep``. The existing steps to select a document type, +enter metadata and tag the document, have been converted to function as +``WizardSteps`` subclasses. The converted steps now live in + +``sources.wizards.WizardStepDocumentType``, ``tag.wizard_steps.WizardStepTags``, +and ``metadata.wizard_steps.WizardStepMetadata``. + +The steps need to define the following methods: + +- ``done``: This method is execute when the wizard finished the last step + an enter the step where the actual file are uploaded. This steps is used + to encode form data into the URL query string that will be passed to the + document upload view for each file uploaded. + +- ``condition``: This method is used to display the step conditionally. + If this method return True it will be displayed during the upload wizard + execution. To skip the step, return False or None. + +- ``get_form_initial``: This method is used to return the initial data + for the step form. Use this method to set up initial values for the step's + form fields. + +- ``step_post_upload_process``: This method will be executed once the + document finishes uploading. Use this method to process the information + encoded in the URL querystring by the step's `done`` method. + +Once the ``WizardStep`` subclass is defined, it needs to be registered. This +is done by calling the ``.register`` method of the ``WizardStep`` class with +the subclass as the argument. Example:: + + WizardStep.register(WizardStepMetadata) + +This statement must be located after the subclass definition. Finally, +the module defining the wizard step must be imported so that it is loaded +with the rest of the code and enabled. The best place to do this is in the +``.ready`` method of the apps' ``apps.py`` module. Example:: + + class TagsApp(MayanAppConfig): + has_rest_api = True + has_tests = True + name = 'tags' + verbose_name = _('Tags') + + def ready(self): + super(TagsApp, self).ready() + from actstream import registry + + from .wizard_steps import WizardStepTags # NOQA + +The ``WizardStep`` class also allows for unregistering existing steps. This +is accomplished by calling the ``.deregister`` method of the ``WizardStep`` +class and passing the subclass as the argument. This method should +also be called inside the ``.ready`` method of an apps' ``apps.py`` +module. Example:: + + + class TagsApp(MayanAppConfig): + has_rest_api = True + has_tests = True + name = 'tags' + verbose_name = _('Tags') + + def ready(self): + super(TagsApp, self).ready() + from actstream import registry + + from metadata.wizard_steps import WizardStepMetadata # NOQA + from sources.wizards import WizardStep # NOQA + from .wizard_steps import WizardStepTags # NOQA + + WizardStep.deregister(WizardStepTags) + + +This will cause the tags assigment step to not be assigned to the upload +wizard anymore. diff --git a/docs/topics/versioning.rst b/docs/topics/versioning.rst index 922c27b34e..2ed26469c2 100644 --- a/docs/topics/versioning.rst +++ b/docs/topics/versioning.rst @@ -8,5 +8,41 @@ version changes in comparison with the previous one. If a new version was uploaded by mistake or such new version is no longer necessary the option to revert to a previous version of the document is provided. +.. blockdiag:: + + blockdiag { + default_shape = roundedbox + orientation = portrait + node_width = 200; + version_1 [ label = "Version 1" ]; + version_2 [ label = "Version 2" ]; + document_1 [ label = "payroll_report.pdf" ]; + document_2 [ label = "payroll_report_fixed.pdf" ]; + upload_1 [ label = "payroll_report.pdf" ]; + upload_2 [ label = "payroll_report_fixed.pdf" ]; + + upload_1 -> version_1 -> document_1; + upload_2 -> version_2 -> document_2; + document_1 -> document_2; + } + Only the interactive document sources (:doc:`sources`) (``Web`` and ``Staging folders``) are available to upload new document versions. + +There is no limit to the number of versions a document can have. + +.. blockdiag:: + + blockdiag { + default_shape = roundedbox + orientation = portrait + node_width = 200; + + document [ label = "payroll_report.pdf" ]; + versions [ label = "Versions", stacked ]; + + document -> versions; + } + +By default, the last version will be showed when working with the document +but any of the versions can be inspected and viewed. diff --git a/requirements/documentation.txt b/requirements/documentation.txt index aa83331dfc..70323dcf71 100644 --- a/requirements/documentation.txt +++ b/requirements/documentation.txt @@ -1,4 +1,5 @@ Sphinx==1.7.1 sphinx-autobuild==0.7.1 +sphinx_rtd_theme==0.2.4 sphinxcontrib-blockdiag==1.5.5