Update documentation

HISTORY.rst

@@ -1,16 +1 @@
-1.0 (XX/07/2014)
-================
-
-- New repository: https://github.com/mayan-edms/mayan-edms
-- Update required version of Django to 1.6
-- Translation update and inclusion of new languages
-- Use of related_name in some models
-- Removal of circular imports
-- Removal of included 3rd party modules
-- Automatic testing and code coverage check
-- Update of required modules and libraries versions
-- Database connection leaks fixes
-- Deletion of detached signatures
-- Removal of fabric based installations
-- New project structure
-- New API system, browseable API, browseable API documentation
+.. include:: docs/releases/1.0.rest

docs/intro/installation.rst

@@ -15,35 +15,21 @@ If using a Fedora_ based Linux distribution get the executable requirements usin
 
     $ sudo yum install -y git gcc tesseract unpaper python-virtualenv ghostscript libjpeg-turbo-devel libpng-devel poppler-util python-devel
 
-Initialize a ``virtualenv`` to deploy the project::
+Initialize a ``virtualenv`` to deploy the project:
 
-    $ virtualenv --no-site-packages venv
+.. code-block:: bash
+
+    $ virtualenv venv
     $ source venv/bin/activate
+    $ pip install mayan-edms==1.0.rc1
 
-Download_ and decompress the latest version of **Mayan EDMS**::
+By default **Mayan EDMS** will create a single file SQLite_ database which makes
+is very easy to start using **Mayan EDMS**. Populate the database with the project's schema doing:
 
-    $ cd venv
-    $ tar -xvzf mayan.tar.gz
+.. code-block:: bash
 
-Or clone the latest development version straight from github::
-
-    $ cd venv
-    $ git clone https://github.com/mayan-edms/mayan-edms.git
-
-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-edms
-    $ pip install -r requirements.txt
-
-By default **Mayan EDMS** will create a single file SQLite_ database which makes is very easy to start using **Mayan EDMS**.
-Populate the database with the project's schema doing::
-
-    $ ./manage.py syncdb --migrate --noinput
-
-
-To test your installation, execute Django’s development server using the ``runserver`` command to launch a local instance of **Mayan EDMS**::
-
-    $ ./manage.py runserver
+    $ mayan-edms.py syncdb --migrate --noinput
+    $ mayan-edms.py runserver
 
 Point your browser to http://127:0.0.1:8000, if everything was installed
 correctly you should see the login screen and panel showing a randomly generated admin password.
@@ -52,6 +38,21 @@ correctly you should see the login screen and panel showing a randomly generated
 Production use
 --------------
 
+To create a custom settings file for **Mayan EDMS**, create your a Python (.py) file
+in the directory: venv/mayan/settings/ with the following basic content::
+
+    # my_settings.py
+
+    from __future__ import absolute_import
+
+    from .local import *
+
+    <Your customized settings>
+
+Then test your settings launch **Mayan EDMS** use::
+
+    $ mayan-edms runserver --settings=mayan.settings.my_settings
+
 After making sure everything is running correctly, stop the runserver command.
 Deploy **Mayan EDMS** using the webserver of your preference. For more information
 on deployment instructions and examples checkout Django's official documentation

docs/releases/1.0.rst

@@ -115,6 +115,17 @@ Mayan EDMS is now licensed under the Apache 2.0 license. This means many
 things but the main change is that inclusion of Mayan EDMS into
 commercial products is now explicitly allowed.
 
+PyPI package
+~~~~~~~~~~~~
+**Mayan EDMS** has been packaged and submitted to the PyPI_ Python Package Index
+making it even easier to install and use.
+
+New REST API
+~~~~~~~~~~~~
+This release feature a completely new REST API and automatic API documentation.
+This new API is also used internally by *Mayan EDMS* itself.
+
+:q
 Upgrading from a previous version
 =================================
 If you installed Mayan EDMS by cloning the Git repository issue the commands::
@@ -143,9 +154,15 @@ The upgrade procedure is now complete.
 
 Backward incompatible changes
 =============================
-* If using the SQLite3 database option, rename the file named `mayan.sqlite` file to `db.sqlite3`
+* If using the SQLite3 database option, rename the file named `mayan.sqlite` file to `db.sqlite3` and
+  move it to the new `media` provided folder.
+* Also move to the `media` folder any `gpg_home`, `document_storage` and `image_cache` folders
+  from your previous installation.
 
 
 Bugs fixed or issues closed
 ===========================
 * None
+
+
+.. _PyPI: https://pypi.python.org/pypi/mayan-edms/

docs/releases/index.rst

@@ -17,8 +17,6 @@ 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.
 
-.. _development_release_notes:
-
 1.0 release
 -----------
 .. toctree::

docs/topics/customization.rst

@@ -15,7 +15,7 @@ an organtization existing applications' look and feel.
 The theme can be changed very easily by setting the :setting:`WEB_THEME_THEME`
 configuration option to one of its valid values.
 
-.. image:: themes.png
+.. image:: ../_static/themes.png
  :alt: themes
 
 ------------
@@ -25,7 +25,7 @@ The amount of information presented at the login screen can also be restricted
 for security or design reasons using :setting:`WEB_THEME_VERBOSE_LOGIN`
 configuration option.
 
-.. image:: mayan-login.png
+.. image:: ../_static/mayan-login.png
  :alt: mayan login screen
 
 -----------
@@ -43,7 +43,7 @@ Some themes such as ``default`` might be more visually appealing to some
 people without the menu icons, for this **Mayan EDMS** provides the
 :setting:`MAIN_DISABLE_ICONS` configuration option.
 
-.. image:: no-icons.png
+.. image:: ../_static/no-icons.png
  :alt: mayan screens with out icons
 
 .. _`Andrea Franz's excellent web app template`: https://github.com/pilu/web-app-theme

docs/topics/development.rst

@@ -12,9 +12,7 @@ issue on the `GitHub issue tracker`_. To submit patches, please send a pull requ
 .. _GitHub: https://github.com/mayan-edms/mayan-edms/
 .. _`GitHub issue tracker`: https://github.com/mayan-edms/mayan-edms/issues
 
-.. _scm:
 
---------------
 Source Control
 --------------
 
@@ -48,10 +46,19 @@ When submitting patches, please place your feature/change in its own branch prio
 .. _git-flow: https://github.com/nvie/gitflow
 .. _Downloads:  https://github.com/mayan-edms/mayan-edms/archives/master
 
-.. _docs:
+
+Contributing changes
+--------------------
+Once your have create and committed some new code or feature, submit a Pull Request.
+Be sure to merge with mayan-edms/master before doing a pull request so that patches
+apply as cleanly as possible.  If there are no conflicts, Pull Requests can be merged
+directly from Github otherwise a manual command line merge has to be done and
+your patches might take longer to get merged.
+
+For more information on how to create Pull Request read: https://help.github.com/articles/using-pull-requests
+or the quick version: https://help.github.com/articles/creating-a-pull-request
 
 
----------
 Debugging
 ---------
 

docs/topics/file_storage.rst

@@ -8,7 +8,7 @@ and stored in a simple flat arrangement in a directory.  This doesn't
 stop access to the files but it is not recommended because moving,
 renaming or updating the files directly would throw the database out
 of sync.  For direct access to the files the recommended way is to create an
-:doc:`index <indexes>`, use the indexing mirroring feature and share the result via 
+:doc:`index <indexes>`, use the indexing mirroring feature and share the result via
 file serving software [#f1]_.
 
 **Mayan EDMS** components are as decoupled from each other as possible,
@@ -19,7 +19,7 @@ storage, so that **Mayan EDMS** can work saving files locally, over the
 network or even across the internet and still operate exactly the same.
 
 The file storage behavior is controlled by the :setting:`DOCUMENTS_STORAGE_BACKEND`
-and should be set to a class or subclass of Django's ``django.core.files.storage.FileSystemStorage`` class.
+and should be set to a class or subclass of Django's ``django.core.files.storage.Storage`` class.
 
 .. rubric:: Footnotes
 

docs/topics/indexes.rst

@@ -16,7 +16,7 @@ Each branch can be a pseudo folder, which can hold other child 'folders' or
 a document container which will have all the links to the documents that
 matched the path to reach the document container.
 
-.. image:: index_template.png
+.. image:: ../_static/index_template.png
  :alt: index template
 
 Index instances
@@ -26,7 +26,7 @@ The template is the skeleton from which an instance of the index is then
 auto-populated with links to the documents depending on the rules of each
 branch of the index evaluated against the metadata and properties of the documents.
 
-.. image:: index_instance.png
+.. image:: ../_static/index_instance.png
  :alt: index instance
 
 Index serving
@@ -35,7 +35,7 @@ Index serving
 Indexes can be mirrored to the operating system filesystem
 using the configuration option
 :setting:`DOCUMENT_INDEXING_FILESYSTEM_SERVING`.
- 
+
 ``settings_local.py``::
 
   # Supposing the 'Sample index' internal name is 'sample_index'
@@ -44,9 +44,9 @@ using the configuration option
   }
 
 This creates an actual directory tree and links to the actual stored files but using
-the filename of the documents as stored in the database. 
+the filename of the documents as stored in the database.
 
-.. image:: indexes.png
+.. image:: ../_static/indexes.png
  :alt: indexes diagram
 
 This filesystem mirror of the index can them be served with Samba_ across the
@@ -57,7 +57,7 @@ The index cannot be edited manually to protect it's integrity, only changing
 the rules or the metadata of the documents would cause the index to be
 regenerated.  For manual organization of documents there are the folders,
 their structure is however flat, and they have to be manually updated and
-curated. 
+curated.
 
 .. _Samba: http://www.samba.org/
 

docs/topics/permissions.rst

@@ -2,7 +2,7 @@
 Permissions
 ===========
 
-**Mayan EDMS** provides very exact control over what activies users can 
+**Mayan EDMS** provides very exact control over what activies users can
 perform.  This control is divided into two levels of operation:
 
 2 tier permissions assignement
@@ -16,13 +16,13 @@ this method could be thought out as a global permission granting level.
 Example: Roles being granted the ``Document view`` permission will be able to view
 **all** documents in existance.
 
-.. image:: permissions.png
+.. image:: ../_static/permissions.png
  :alt: 2-tier permission diagram
-  
-  
+
+
 3 tier access control
 =====================
-  
+
 When more control is desired over which objects
 actors(user, groups and roles) can exercise an action this method should be
 used.  Under this level, actors are granted a
@@ -30,9 +30,9 @@ permission but only in relation to a selected object.  Example: Granting user
 ``Joe`` the ``Document view`` access control for document ``Payroll``,
 would allow him to view this document only.
 
-.. image:: ACL.png
+.. image:: ../_static/ACL.png
  :alt: 3-tier access control diagram
-  
+
 The permission system enforces inheritance by first checking if the user
 has a global permission, is a member of a group or a role that has a global
 permission and if not then checks to see if that user, a group or role to
@@ -51,13 +51,13 @@ One of the specifics of the 3 tier access control in contrast with the 2 tier ac
 
 **Example 1.** Each user have to access only the documents that he uploads
 
-The example will show how to restrict a user in order not to view documents uploaded by other users, but only by himself. For that purpose we have to restrict the access to something that does not exist yet. The system must know that before the actual upload in order to act accordingly. This is where Default ACLs come in place. 
+The example will show how to restrict a user in order not to view documents uploaded by other users, but only by himself. For that purpose we have to restrict the access to something that does not exist yet. The system must know that before the actual upload in order to act accordingly. This is where Default ACLs come in place.
 
 Follow the steps:
     1. Enter **Mayan EDMS** with user that has administrative rights.
     2. Go to Setup menu. Enter Default ACLs submenu.
     3. Click ``New holder`` next to the class Documents. From the list of users choose the special user Creator. Give the permission ``View Documents`` to the Creator.
-    4. Go back to Setup menu. Go to Users and create the users ``Pedro`` and ``Sancho``. 
+    4. Go back to Setup menu. Go to Users and create the users ``Pedro`` and ``Sancho``.
     5. Go back to Setup menu. Go to Groups and create the group ``Employees``. Click to members of the groups and add ``Pedro`` and ``Sancho`` to that group.
     6. Go back to Setup menu. Go to Roles submenu. Create the role ``Uploaders``. Give the permission ``Create documents`` to the role. Add the group ``Employees`` as a member to that role.
     7. Now enter **Mayan EDMS** with ``Pedro`` and ``Sancho`` one after another and upload documents. Pedro should not see the documents that ``Sancho`` uploaded and vice versa. He should see only documents uploaded by himself.

docs/topics/versioning.rst

@@ -2,24 +2,24 @@
 Document versioning
 ===================
 
-**Mayan EDMS** has the ability to store different versions of the same 
-document.  Users are provided with a very comprehensive but easy to use 
-version numbering system that allows specifying a major, minor or micro 
+**Mayan EDMS** has the ability to store different versions of the same
+document.  Users are provided with a very comprehensive but easy to use
+version numbering system that allows specifying a major, minor or micro
 version number increase.
 
-.. image:: versioning.png
+.. image:: ../_static/versioning.png
  :alt: versioning diagram
 
-A comment field is also provided to allow users 
-to summarize the new verdion changes in comparison with the previous 
-one.  If a new version was uploded by mistake or such new version is no 
-longer necessary **Mayan EDMS** provides the option to revert to a previous 
+A comment field is also provided to allow users
+to summarize the new verdion changes in comparison with the previous
+one.  If a new version was uploded by mistake or such new version is no
+longer necessary **Mayan EDMS** provides the option to revert to a previous
 version of the document.
 
-To upload a new document version, select an existing document, click on the 
-version tab of the document, and click on the 'upload new version' on the 
-side bar.  A new view very similar to the new document upload view will 
-appear show the same interactive document sources that have been defined, 
-but with new options to specify the new version number and an optional  
-comment. 
+To upload a new document version, select an existing document, click on the
+version tab of the document, and click on the 'upload new version' on the
+side bar.  A new view very similar to the new document upload view will
+appear show the same interactive document sources that have been defined,
+but with new options to specify the new version number and an optional
+comment.