From 60176ada09982a9cbe43eaa2a7b1cf8f6451b4f2 Mon Sep 17 00:00:00 2001 From: Roberto Rosario Date: Sun, 12 Feb 2012 17:12:42 -0400 Subject: [PATCH] Documentation updates --- docs/faq/index.rst | 55 ++++++++++++-------------- docs/topics/development.rst | 51 ++++++++++++++++++++++-- docs/topics/document_visualization.rst | 11 ++++-- docs/topics/settings.rst | 34 ++++++++++------ docs/topics/smart_links.rst | 2 +- 5 files changed, 103 insertions(+), 50 deletions(-) diff --git a/docs/faq/index.rst b/docs/faq/index.rst index b695062027..f24adbae02 100644 --- a/docs/faq/index.rst +++ b/docs/faq/index.rst @@ -7,8 +7,7 @@ Frequently asked questions and solutions Database related ---------------- -Q: PostgreSQL vs. MySQL -~~~~~~~~~~~~~~~~~~~~~~~ +**Q: PostgreSQL vs. MySQL** Since Django abstracts database operations from a functional point of view **Mayan EDMS** will behave exactly the same either way. The only concern @@ -19,8 +18,7 @@ structure is left in a transitory state and has to be reverted manually before trying again. -Q: _mysql_exceptions. OperationalError: (1267, "Illegal mix of collations (latin1_swedish_ci, IMPLICIT) and (utf8_general_ci, COERCIBLE) for operation '='") -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Q: _mysql_exceptions. OperationalError: (1267, "Illegal mix of collations (latin1_swedish_ci, IMPLICIT) and (utf8_general_ci, COERCIBLE) for operation '='")** * Solution:: @@ -39,8 +37,7 @@ Q: _mysql_exceptions. OperationalError: (1267, "Illegal mix of collations (latin - http://stackoverflow.com/questions/1073295/django-character-set-with-mysql-weirdness -Q: Incorrect string value: ``'\xE2\x80\x95rs6...'`` for column ``'content'`` at row 1 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Q: Incorrect string value: ``'\xE2\x80\x95rs6...'`` for column ``'content'`` at row 1** When using ``MySQL`` and doing OCR on languages other than English @@ -54,8 +51,7 @@ When using ``MySQL`` and doing OCR on languages other than English Document sharing ---------------- -Q: File system links not showing when serving content with ``Samba`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Q: File system links not showing when serving content with ``Samba``** * Solution: @@ -81,8 +77,7 @@ Q: File system links not showing when serving content with ``Samba`` Document handling ----------------- -How to store documents outside of **Mayan EDMS's** path -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**How to store documents outside of **Mayan EDMS's** path** * Sub class Django's ``FileSystemStorage`` class: @@ -102,8 +97,7 @@ How to store documents outside of **Mayan EDMS's** path DOCUMENTS_STORAGE_BACKEND = CustomStorage -Q: How to enable the ``GridFS`` storage backend -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Q: How to enable the ``GridFS`` storage backend** * Solution: @@ -114,8 +108,7 @@ Q: How to enable the ``GridFS`` storage backend - Filesystem metadata indexing will not work with this storage backend as the files are inside a ``MongoDB`` database and can't be linked (at least for now) -Q: How do you upload a new version of an existing file? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Q: How do you upload a new version of an existing file?** * Solution: @@ -125,20 +118,21 @@ Q: How do you upload a new version of an existing file? view as the ``Upload new document`` but you will be able to specify version number and comments for the new version being uploaded. -Q: Site search is slow -~~~~~~~~~~~~~~~~~~~~~~ +**Q: Site search is slow** * Add indexes to the following fields: - ``documents_document`` - description, recommended size: 160 - ``documents_documentpage`` - content, recommended size: 3000 + +This is a temporary solution as **Mayan EDMS** will soon be moving to a +specialized full text search solution. Webserver --------- -Q: How to enable x-sendile support for ``Apache`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Q: How to enable x-sendile support for ``Apache``** * If using Ubuntu execute the following:: @@ -157,8 +151,7 @@ Q: How to enable x-sendile support for ``Apache`` OCR --- -Q: The included version of ``unoconv`` in my distribution is too old -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Q: The included version of ``unoconv`` in my distribution is too old** * Only the file 'unoconv' file from https://github.com/dagwieers/unoconv is needed. Put it in a user designated directory for binaries such as /usr/local/bin and @@ -166,12 +159,16 @@ Q: The included version of ``unoconv`` in my distribution is too old CONVERTER_UNOCONV_PATH = '/usr/local/bin/unoconv' - +If you already have office or text documents uploaded into **Mayan EDMS**, +after setting up and testing ``unoconv`` by hand, go to 'Tools', +'Maintenance', 'Update office documents' page count', this will force a +re-detection and re-processing of any document found to be of office format. + + Deployments ----------- -Q: Is virtualenv required as specified in the documentation? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Q: Is virtualenv required as specified in the documentation?** * It is not necessary, it's just a strong recommendation mainly to reduce dependency conflicts by isolation from the main Python system install. @@ -182,8 +179,7 @@ Q: Is virtualenv required as specified in the documentation? Mayan to stop working for no apparent reason. -Q: Mayan EDMS installed correctly and works, but static files are not served -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Q: Mayan EDMS installed correctly and works, but static files are not served** Django's development server doesn't serve static files unless the ``DEBUG`` option is set to ``True``, this mode of operation should only be used for @@ -201,8 +197,7 @@ Other ----- -Q: How to connect Mayan EDMS to an Active Directory tree -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Q: How to connect Mayan EDMS to an Active Directory tree** I used these two libraries as they seemed the most maintained from the quick search I did. @@ -249,8 +244,10 @@ For a more advanced example check this StackOverflow question: http://stackoverflow.com/questions/6493985/django-auth-ldap -Q: Can you change the display order of documents...i.e can they be in alphabetical order? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Q: Can you change the display order of documents...i.e can they be in alphabetical order?** A the moment no, but it is something being considered. + + + diff --git a/docs/topics/development.rst b/docs/topics/development.rst index b55371ac69..8521d397af 100644 --- a/docs/topics/development.rst +++ b/docs/topics/development.rst @@ -51,9 +51,9 @@ To familiarize yourself with the technical details of the project read the :ref: .. _docs: ------------------ +------------- Documentation ------------------ +------------- The documentation is written in `reStructured Text`_ format. @@ -74,8 +74,51 @@ You can also generate the documentation in format other than HTML. .. _Sphinx: http://sphinx.pocoo.org ---------------- +------------ Translations ---------------- +------------ Translations are now being handled online via the **Transifex** website: https://www.transifex.net/projects/p/mayan-edms/ +To create a translation team for a new language or contribute to an already +existing language translation, create a **Transifex** account and contact +the team coordinator of the respective language in which you are interested. + +--------- +Debugging +--------- + +**Mayan EDMS** makes extensive use of Django's new `logging capabilities`_. +To enable debug logging for the documents app for example 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', + }, + } + } + +.. _`logging capabilities`: https://docs.djangoproject.com/en/dev/topics/logging diff --git a/docs/topics/document_visualization.rst b/docs/topics/document_visualization.rst index daa9cead49..cfedc23ad3 100644 --- a/docs/topics/document_visualization.rst +++ b/docs/topics/document_visualization.rst @@ -7,8 +7,9 @@ The philosophy in place is to try to avoid having users download a documents and **Mayan EDMS** to be able to see them, so in essence making **Mayan EDMS** a visualization tool too. The conversion backend is a stack of functions, first the mimetype is evaluated, if it is an office document it is passed -to Libreoffice_ working in headless mode (and managed by supervisor) -via unoconv for conversion to PDF_. The PDF_ is stored in a temporary +to LibreOffice_ working in headless mode (and managed by supervisor_) +via unoconv_ (more information about ``unoconv`` can be found in the :doc:`FAQ section <../faq/index>`) +for conversion to PDF_. The PDF_ is stored in a temporary cache along side all the other files that were not office documents, from here they are inspected to determine the page count and the corresponding blank database entires are created. After the database @@ -17,7 +18,7 @@ option :setting:`CONVERTER_GRAPHICS_BACKEND` and a high resolution master preview of each file is generated and stored in the persistent cache. From the master previews in the persistent cache, volatile previews are then created on demand for the different sizes requested -(thumbnail, page preview, full preview) and rotate interactively +(thumbnail, page preview, full preview) and rotated interactively in the details view. @@ -31,4 +32,6 @@ before they can be previewed and text can be extracted. .. _PDF: http://en.wikipedia.org/wiki/Portable_Document_Format -.. _Libreoffice: http://www.libreoffice.org/ +.. _LibreOffice: http://www.libreoffice.org/ +.. _unoconv: https://github.com/dagwieers/unoconv/ +.. _supervisor: http://supervisord.org/introduction.html diff --git a/docs/topics/settings.rst b/docs/topics/settings.rst index a57beb99b5..5d17d1779e 100644 --- a/docs/topics/settings.rst +++ b/docs/topics/settings.rst @@ -129,7 +129,29 @@ The path where the visual representations of the documents are stored for fast d Converter ========= +.. setting:: CONVERTER_GRAPHICS_BACKEND + +**CONVERTER_GRAPHICS_BACKEND** + +Default: ``converter.backends.python`` +Graphics conversion backend to use. Options are: + +* ``converter.backends.imagemagick`` - Wrapper for ImageMagick + + * Use the :setting:`CONVERTER_IM_CONVERT_PATH` and :setting:`CONVERTER_IM_IDENTIFY_PATH` to specify the binary files locations. + +* ``converter.backends.graphicsmagick`` - Wrapper for GraphicsMagick + + * Use the :setting:`CONVERTER_GM_PATH` and :setting:`CONVERTER_GM_SETTINGS` to specify the binary file location and customized settings. + +* ``converter.backends.python`` - Wrapper for Pillow_ and Ghostscript_ + + +.. _Pillow: http://pypi.python.org/pypi/Pillow +.. _Ghostscript: http://www.ghostscript.com/ + + .. setting:: CONVERTER_IM_CONVERT_PATH **CONVERTER_IM_CONVERT_PATH** @@ -170,18 +192,6 @@ fine tune it's functionality as explained in the `GraphicsMagick documentation`_ .. _GraphicsMagick documentation: http://www.graphicsmagick.org/convert.html#conv-opti - -.. setting:: CONVERTER_GRAPHICS_BACKEND - -**CONVERTER_GRAPHICS_BACKEND** - -Default: ``converter.backends.python`` - -Graphics conversion backend to use. Options are: - -* ``converter.backends.imagemagick`` - Wrapper for ImageMagick -* ``converter.backends.graphicsmagick`` - Wrapper for GraphicsMagick -* ``converter.backends.python`` - Wrapper for Pillow and Ghostscript .. setting:: CONVERTER_UNOCONV_PATH diff --git a/docs/topics/smart_links.rst b/docs/topics/smart_links.rst index ea2559e965..07db50a9d0 100644 --- a/docs/topics/smart_links.rst +++ b/docs/topics/smart_links.rst @@ -4,6 +4,6 @@ Smart links Smart links are usefull for navigation between documents. They are rule based but don't created any organizational structure just show the documents -that match the rules as evaluated against the metadata of currently +that match the rules as evaluated against the metadata of the currently displayed document. The index is global, the smart links are dependant on the current document the user is viewing.