diff --git a/docs/changelog.rst b/docs/changelog.rst index a39b9d06bc..d3005b0896 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -104,7 +104,7 @@ Version 0.8.0 * Improve link highlighting * Navigation improvements -* Documents with an unknonw file format now display a mime type place +* Documents with an unknown file format now display a mime type place holder icon instead of a error icon * Mayan now does pre caching of document visual representation improving overall thumbnail, preview and display speed @@ -212,7 +212,7 @@ Version 0.7.3 * Multi item links are now displayed on top of generic lists as well as on the bottom * Spanish translation updates -* Updated requirements to use the latests development version of +* Updated requirements to use the latest development version of django-mptt * Improved user folder document removal views * Added ability to specify default metadata or metadataset per @@ -281,10 +281,10 @@ Version 0.5 * Disabled ``CELERY_DISABLE_RATE_LIMITS`` by default * Implement local task locking using Django locmem cache backend * Added doc extension to office document format list -* Removed redundant tranformation calculation +* Removed redundant transformation calculation * Make sure OCR in processing documents cannot be deleted * PEP8, pylint cleanups and removal of relative imports -* Removed the obsolote ``DOCUMENTS_GROUP_MAX_RESULTS`` setting option +* Removed the obsolete ``DOCUMENTS_GROUP_MAX_RESULTS`` setting option * Improved visual appearance of messages by displaying them outside the main form * Added link to close all notifications with one click @@ -292,7 +292,7 @@ Version 0.5 setting: ``OCR_QUEUE_PROCESSING_INTERVAL`` * Added detection and reset of orphaned ocr documents being left as 'processing' when celery dies -* Improved unkwnown format detection in the graphicsmagick backend +* Improved unknown format detection in the graphicsmagick backend * Improved document convertion API * Added initial support for converting office documents (only ods and docx tested) @@ -424,7 +424,7 @@ Version 0.5 implemented by Django * Moved navigation code to its own app * Reimplemented OCR delay code, only delay new document - Added a new field: delay, update your database schema acordinging + Added a new field: delay, update your database schema accordingly * Made the concurrent ocr code more granular, per node, every node can handle different amounts of concurrent ocr tasks Added a new field: node_name, update your database schema acordinging diff --git a/docs/contributors.rst b/docs/contributors.rst index b0bc3f8197..fb73411de2 100644 --- a/docs/contributors.rst +++ b/docs/contributors.rst @@ -1,3 +1,5 @@ +.. _contributors: + ============ Contributors ============ @@ -5,7 +7,7 @@ Contributors How to contribute? ------------------ -You can help further the development of Mayan EDMS by reporting bugs, submitting documentation, patches, with monetary or hardware donations. +You can help further the development of **Mayan EDMS** by reporting bugs, submitting documentation, patches, with monetary or hardware donations. Bug reports ----------- diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 0000000000..869669d5b6 --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,71 @@ +.. _development: + +Development +=========== + +**Mayan EDMS** is under active development, and contributions are welcome. + +If you have a feature request, suggestion, or bug reports, please open a new +issue on the `GitHub issue tracker`_. To submit patches, please send a pull request on GitHub_. Contributors are credited accordingly on the :ref:`contributors` section. + + +.. _GitHub: http://github.com/rosarior/mayan/ +.. _`GitHub issue tracker`: https://github.com/rosarior/mayan/issues + +.. _scm: + +-------------- +Source Control +-------------- + + +**Mayan EDMS** source is controlled with Git_ + +The project is publicly accessable, hosted and can be cloned from **GitHub** using:: + + ``git clone git://github.com/rosarior/mayan.git`` + + +Git branch structure +-------------------- + +**Mayan EDMS** follows the model layout by Vincent Driessen in his `Successful Git Branching Model`_ blog post. Git-flow_ is a great tool for managing the repository in this way. + +``develop`` + The "next release" branch. Likely unstable. +``master`` + Current production release (|version|). + +Each release is tagged and available for download on the Downloads_ section of the **Mayan EDMS** repository on GitHub_ + +When submitting patches, please place your feature/change in its own branch prior to opening a pull request on GitHub_. +To familiarize yourself with the technical details of the project read the :ref:`internals` section. + +.. _Git: http://git-scm.org +.. _`Successful Git Branching Model`: http://nvie.com/posts/a-successful-git-branching-model/ +.. _git-flow: http://github.com/nvie/gitflow +.. _Downloads: https://github.com/rosarior/mayan/archives/master + +.. _docs: + +----------------- +Documentation +----------------- + +The documentation is written in `reStructured Text`_ format. + +The documentation lives in ``docs`` directory. In order to build it, you will first need to install Sphinx_. :: + + $ pip install sphinx + + +Then, to build an HTML version of the documentation, simply run the following from the **docs** directory:: + + $ make html + +Your ``docs/_build/html`` directory will then contain an HTML version of the documentation, ready for publication on most web servers. + +You can also generate the documentation in format other than HTML. + +.. _`reStructured Text`: http://docutils.sourceforge.net/rst.html +.. _Sphinx: http://sphinx.pocoo.org diff --git a/docs/faq.rst b/docs/faq.rst index 4dfae06d9d..05f9248cae 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -8,7 +8,7 @@ Frequently asked questions and solutions Incorrect string value: ``'\xE2\x80\x95rs6...'`` for column ``'content'`` at row 1 ---------------------------------------------------------------------------------- -When using ``MySQL`` and doing OCR on languages other than english +When using ``MySQL`` and doing OCR on languages other than English * Solution: @@ -41,8 +41,8 @@ File system links not showing when serving content with ``Samba`` - Ref: 1- http://www.samba.org/samba/docs/man/manpages-3/smb.conf.5.html -How to store documents outside Mayan's path -------------------------------------------- +How to store documents outside of **Mayan EDMS's** path +------------------------------------------------------- * Sub class Django's ``FileSystemStorage`` class: @@ -81,9 +81,9 @@ Site search is slow * Add indexes to the following fields: - - ``documents_document`` - description, recomended size: 160 - - ``documents_documentmetadata`` - value, recomended size: 80 - - ``documents_documentpage`` - content, recomended size: 3000 + - ``documents_document`` - description, recommended size: 160 + - ``documents_documentmetadata`` - value, recommended size: 80 + - ``documents_documentpage`` - content, recommended size: 3000 How to enable x-sendile support for ``Apache`` diff --git a/docs/features.rst b/docs/features.rst index dcccdcdedf..3ad5262fbd 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -2,20 +2,60 @@ Features ======== -* User defined meta-data fields -* Dynamic default values for metadata -* Filesystem integration -* User defined document unique identifier and checksum algorithms -* Local file or server side file uploads -* Batch upload many documents with the same meta-data -* Previews for a great deal of image formats, including PDF -* Full text searching -* Configurable document grouping -* Permissions and roles support -* Multi page document support -* Distributed OCR processing -* Multilingual user interface (English, Spanish) -* Multilingual OCR support -* Duplicated document search -* Plugable storage backends (File based and GridFS included) -* Color coded tagging +* User defined metadata fields and meta data sets. + + * Metadata fields can be grouped into sets per technical, legal or structural requirements such as the `Dublin core`_ + +.. _`Dublin core`: http://dublincore.org/metadata-basics/ + +* Dynamic default values for metadata. + + * Metadata fields can have an initial value which can be static or determined by an user provided Python code snipped. + +* Filesystem integration. + + * If enabled, the document database index can be mirrored in the filesystem of the hosting computers and shared via Samba_ or any other method to clients computers on a network. + +.. _Samba: http://www.samba.org/ + +* User defined document unique identifier and checksum algorithms. + + * Users can alter the default method used to uniquely indentify documents. + +* Documents can be uploaded from different sources. + + * Local file or server side file uploads. + +* Batch upload many documents with the same metadata. +* Previews for a great deal of image formats, including PDF. + + * **Mayan EDMS** provides different file conversion backends with different levels of functionality and requirements to adapt to different deployment environments. + +* Full text searching. +* Configurable document grouping. + + * Automatic linking of documents based on metadata values or document properties. + +* Permissions and roles support. + + * User can created many different roles and are not limited to the traditional limited admin, operator, guest paradigm. + +* Multi page document support. + + * Multiple page PDFs and TIFFs files supported. + +* Distributed OCR processing. + + * The task of transcribing text from documents via OCR can be distributed among several physical or virtual computers to decrease load and increase availability. + +* Multilingual user interface (English, Spanish). + + * **Mayan EDMS** is written using the Django_ framework which natively support Unicode, this coupled with the use of text templates allows **Mayan EDMS** to be translated to practically any language spoken in the world, by default two translations are provided: English and Spanish. + +.. _Django: https://www.djangoproject.com/ + +* Multilingual OCR support. +* Duplicated document search. +* Plugable storage backends (File based and GridFS included). +* Color coded tagging. +* Staging folders to receive scanned documents directly from network attached scanners. diff --git a/docs/index.rst b/docs/index.rst index 17f089445a..878a9a4377 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,7 +2,7 @@ Mayan EDMS ========== -Open source, Django_ based document manager with custom metadata indexing, file serving integration and OCR capabilities. +Open source, Django_ based document manager with custom metadata indexing, file serving integration and OCR_ capabilities. .. _Django: http://www.djangoproject.com/ @@ -10,15 +10,27 @@ Open source, Django_ based document manager with custom metadata indexing, file :Website: http://bit.ly/mayan-edms :Source: http://github.com/rosarior/mayan :Video: http://bit.ly/pADNXv +:Issue tracker: http://github.com/rosarior/mayan/issues Overview ======== -Bulk upload documents directly or by using a staging folder to receive -scanned documents. Organize using document classes and custom meta-data -as well as automatic document grouping. Find document by means of full -text searching, either meta-data, document properties, content extracted -from PDFs or transcribed by OCR. +**Mayan EDMS** started as a simple project whose only requirement was the storage of PDF files, from there it has grown into a complete electronic document management solution. +**Mayan EDMS** can optimize an organization's bulk upload, storage and retrieval or documents. +Documents are organized using document classes, user defined metadata fields as well as automatic document grouping and indexing. Documents can be retrieved from the document index or by means of full +text searching. Users can search for terms in the document's metadata, properties or contents extracted from PDFs or transcribed by OCR_. **Mayan EDMS** is written in Python_ using the Django_ framework, which makes it very agile and fast, specially when compared with existing Java based solutions. +Being based on patent free, `Open source`_ technologies, **Mayan EDMS** provides legal safety to users and organizations, as well as peace of mind as documents and all related information is stored in open source and transparent formats allowing portability and avoiding `vendor lock-in`_. +Being written using Python_, **Mayan EDMS** runs on many POSIX compliant operating systems, this coupled with many configuration parameters, allows **Mayan EDMS** to be deployed on many hardware and software configurations such as single server based, clusters, virtualized and cloud based hosting giving adopters the choice of using the infrastructure of their choice. +On hosting providers that support Django_ such as DjangoZoom_, **Mayan EDMS** can be deployed in under 2 minutes with just a few clicks of the mouse [#]_. + +.. [#] "Deploying Mayan EDMS on DjangoZoom.com" @ Youtube (http://bit.ly/mayan-djangozoom) +.. _`vendor lock-in`: https://secure.wikimedia.org/wikipedia/en/wiki/Vendor_lock-in +.. _Python: http://www.python.org/ +.. _Django: http://www.djangoproject.com/ +.. _OCR: https://secure.wikimedia.org/wikipedia/en/wiki/Optical_character_recognition +.. _`Open source`: https://secure.wikimedia.org/wikipedia/en/wiki/Open_source +.. _DjangoZoom: http://djangozoom.com/ + Contents ======== @@ -30,8 +42,9 @@ Contents requirements installation settings - technical updates + development + technical contributors credits faq diff --git a/docs/installation.rst b/docs/installation.rst index 8a9752cd8e..ca937cc7ae 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,7 +1,7 @@ ============ Installation ============ -Mayan EDMS should be installed like any other Django project and preferably using ``virtualenv``. +**Mayan EDMS** should be installed like any other Django project and preferably using ``virtualenv``. If using a Debian_ or Ubuntu_ based Linux distribution getting the executable requirements is as easy as:: @@ -11,7 +11,7 @@ To initialize a ``virtualenv`` to deploy the project do:: $ virtualenv --no-site-packages mayan -Download_ and uncompress the latest version of Mayan:: +Download_ and decompress the latest version of **Mayan EDMS**:: $ cd mayan $ tar -xvzf mayan.tar.gz @@ -21,7 +21,7 @@ Or clone the latest development version straight from github:: $ cd mayan $ git clone git://github.com/rosarior/mayan.git -To install the python depencies ``easy_install`` can be used, however for easier retrieval a production dependencies file is included, to use it execute:: +To install the python dependencies ``easy_install`` can be used, however for easier retrieval a production dependencies file is included, to use it execute:: $ cd mayan $ source ../bin/activate diff --git a/docs/license.rst b/docs/license.rst index 02cf0ef6d4..9e64767358 100644 --- a/docs/license.rst +++ b/docs/license.rst @@ -2,7 +2,7 @@ License ======= -Mayan EDMS is distributed under the `GNU GPL Version 3.0 License`_. +**Mayan EDMS** is distributed under the `GNU GPL Version 3.0 License`_. The complete license terms are included below. .. _`GNU GPL Version 3.0 License`: https://www.gnu.org/licenses/gpl-3.0.html diff --git a/docs/requirements.rst b/docs/requirements.rst index c87a9fe6bd..12ce20999d 100644 --- a/docs/requirements.rst +++ b/docs/requirements.rst @@ -1,7 +1,7 @@ ============ Requirements ============ -Mayan EDMS supports various levels of functionality because of this +**Mayan EDMS** supports various levels of functionality, because of this requirements can vary for each individual deployment. Basic requirements @@ -40,15 +40,15 @@ To store documents in a GridFS database * ``GridFS`` - a storage specification for large objects in ``MongoDB`` * ``MongoDB`` - a scalable, open source, document-oriented database -Enchanced MIME detection +Enhanced MIME detection ------------------------ -* ``libmagic`` - MIME detection library, if not installed Mayan will fall back to using python's simpler mimetype built in library +* ``libmagic`` - MIME detection library, if not installed **Mayan EDMS** will fall back to using python's simpler mimetype built in library * ``python-magic`` - A python wrapper for libmagic Image conversion backends ------------------------- -Mayan has the ability to switch between different image conversion backends, at the moment these three are supported: +**Mayan EDMS** has the ability to switch between different image conversion backends, at the moment these three are supported: * ``ImageMagick`` - Convert, Edit, Or Compose Bitmap Images. * ``GraphicMagick`` - Robust collection of tools and libraries to read, write, and manipulate an image. diff --git a/docs/settings.rst b/docs/settings.rst index 3fcfcd3772..0f95b103d4 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -2,7 +2,7 @@ Settings ======== -Mayan EDMS has many configuration options that make it very adaptable to +**Mayan EDMS** has many configuration options that make it very adaptable to different server configurations. Documents @@ -134,7 +134,7 @@ Converter Default: ``/usr/bin/unoconv`` -Groupping +Grouping --------- .. data:: GROUPING_SHOW_EMPTY_GROUPS @@ -377,7 +377,7 @@ Main User management ------ +--------------- .. data:: ROLES_DEFAULT_ROLES diff --git a/docs/technical.rst b/docs/technical.rst index ccff67154a..3f33fd15c1 100644 --- a/docs/technical.rst +++ b/docs/technical.rst @@ -1,3 +1,5 @@ +.. _internals: + ========= Internals ========= @@ -5,3 +7,36 @@ Internals |architecture| .. |architecture| image:: _static/mayan_architecture.png + + +**Mayan EDMS** is not a single program, but a collection of different Django apps, each designed to provide a specific functionality. + +* common - Holds code and provide a central place to put code thats used by all the other apps. +* document_indexing +* history +* main - Can be thought as the project app, is small on purpose. +* navigation - Handles the complex automatic creation of hyper text links. +* project_setup +* scheduler +* storage - Abstracts the storage of documents. +* web_theme - Handles the presentation of the HTML and CSS to the user. +* converter - Abstracts the convertions between file formats, calls the backends of which are wrappers for ImageMagick, GraphicsMagick and python's PIL coupled with ghostscript. +* documents - The main app, handles the Document and DocumentPage classes. +* folders +* job_processor +* metadata +* ocr +* project_tools +* smart_settings +* tags - Handles Document tagging, it is a wrapper for django-taggit_. +* document_comments - Handles document comments it's a wrapper for `Django\'s comment framework`_. +* dynamic_search +* grouping +* mimetype - Handles file mimetype detection using python-magic or falling back to Pythons mimetype library, also handles the mimetype icon library. +* permissions - All the other apps register their permissions with this one. +* sources - Handles the document file sources definitions. +* user_management - User and group management, it is a wrapper for Django's user creating and authentication system. + + +.. _`Django\'s comment framework`: https://docs.djangoproject.com/en/dev/ref/contrib/comments/ +.. _django-taggit: https://github.com/alex/django-taggit