more documentation.

docs/administration.rst

@@ -27,75 +27,74 @@ Restoring
 Updating paperless
 ##################
 
-.. warning::
-
-    This section is not updated yet.
-
 For the most part, all you have to do to update Paperless is run ``git pull``
-on the directory containing the project files, and then use Django's
-``migrate`` command to execute any database schema updates that might have been
-rolled in as part of the update:
+on the directory containing the project files, and then rebuild the docker
+image.
 
 .. code-block:: shell-session
 
-    $ cd /path/to/project
+    $ cd /path/to/paperless
     $ git pull
-    $ pip install -r requirements.txt
-    $ cd src
-    $ ./manage.py migrate
-
-Note that it's possible (even likely) that while ``git pull`` may update some
-files, the ``migrate`` step may not update anything.  This is totally normal.
-
-Additionally, as new features are added, the ability to control those features
-is typically added by way of an environment variable set in ``paperless.conf``.
-You may want to take a look at the ``paperless.conf.example`` file to see if
-there's anything new in there compared to what you've got in ``/etc``.
-
-If you are using docker the update process is similar:
-
-.. code-block:: shell-session
-
-    $ cd /path/to/project
-    $ git pull
-    $ docker build -t paperless .
-    $ docker-compose run --rm consumer migrate
-    $ docker-compose up -d
 
 If ``git pull`` doesn't report any changes, there is no need to continue with
 the remaining steps.
 
-This depends on the route you've chosen to run paperless.
+After that, check if ``docker-compose.yml.example`` has changed. Update your
+``docker-compose.yml`` file if necessary.
 
-    a.  If you are not using docker, update python requirements. Paperless uses
-        `Pipenv`_ for managing dependencies:
+.. code-block:: shell-session
 
-        .. code:: bash
+    $ docker-compose down
+    $ docker build -t jonaswinkler/paperless-ng .
+    $ docker-compose up -d
 
-            $ pip install --upgrade pipenv
-            $ cd /path/to/paperless
-            $ pipenv install
+The docker image will take care of database migrations during startup.
 
-        This creates a new virtual environment (or uses your existing environment)
-        and installs all dependencies into it. Running commands inside the environment
-        is done via
+Updating paperless without docker
+=================================
 
-        .. code:: bash
+Since paperless now involves a single page app that has to be built from source,
+updating paperless manually is somewhat more complicated.
 
-            $ cd /path/to/paperless/src
-            $ pipenv run python3 manage.py my_command
-        
-        You will also need to build the frontend each time a new update is pushed.
-        See updating paperless for more information. TODO REFERENCE
-        
-    b.  If you are using docker, build the docker image.
+1.  Update python requirements. Paperless uses
+    `Pipenv`_ for managing dependencies:
 
-        .. code:: bash
+    .. code:: shell-session
 
-            $ docker build -t jonaswinkler/paperless-ng:latest .
+        $ pip install --upgrade pipenv
+        $ cd /path/to/paperless
+        $ pipenv install
+
+    This creates a new virtual environment (or uses your existing environment)
+    and installs all dependencies into it.
+    
+2.  You will also need to build the frontend each time a new update is pushed.
+    You need `npm <https://www.npmjs.com/get-npm>`_ for this.
+
+    .. code:: shell-session
+
+        $ cd src-ui
+        $ npm install @angular/cli
+        $ ng build --prod
+    
+    This will build the application and move the relevant files to a location
+    within the django app (``src/documents/static/frontend``) at which django
+    expects to find the files.
+
+3.  Collect static files, namely the newly created frontend files.
+
+    .. code:: shell-session
+
+        $ cd src
+        $ pipenv run python3 manage.py collectstatic --clear
+    
+4.  Migrate the database.
+
+    .. code:: shell-session
+
+        $ cd src
+        $ pipenv run python3 manage.py migrate
 
-        Copy either docker-compose.yml.example or docker-compose.yml.sqlite.example
-        to docker-compose.yml and adjust the consumption directory.
         
 Management utilities
 ####################
@@ -246,6 +245,7 @@ the index and usually makes queries faster and also ensures that the
 autocompletion works properly. This command is regularly invoked by the task
 scheduler.
 
+.. _utilities-renamer:
 
 Managing filenames
 ==================
@@ -269,7 +269,7 @@ The command takes no arguments and processes all your documents at once.
 
 .. _utilities-encyption:
 
-Managing encrpytion
+Managing encryption
 ===================
 
 Documents can be stored in Paperless using GnuPG encryption.

docs/advanced_usage.rst

@@ -240,3 +240,84 @@ example, you can take a look at ``post-consumption-example.sh`` in the
 ``scripts`` directory in this project.
 
 The post consumption script cannot cancel the consumption process.
+
+
+File name handling
+##################
+
+By default, paperless stores your documents in the media directory and renames them
+using the identifier which it has assigned to each document. You will end up getting
+files like ``0000123.pdf`` in your media directory. This isn't necessarily a bad
+thing, because you normally don't have to access these files manually. However, if
+you wish to name your files differently, you can do that by adjustng the
+``PAPERLESS_FILENAME_FORMAT`` settings variable.
+
+This variable allows you to configure the filename (folders are allowed!) using
+placeholders. For example, setting
+
+.. code:: bash
+
+    PAPERLESS_FILENAME_FORMAT={created_year}/{correspondent}/{title}
+
+will create a directory structure as follows:
+
+.. code::
+
+    2019/
+      my_bank/
+        statement-january-0000001.pdf
+        statement-february-0000002.pdf
+    2020/
+      my_bank/
+        statement-january-0000003.pdf
+      shoe_store/
+        my_new_shoes-0000004.pdf
+
+Paperless appends the unique identifier of each document to the filename. This
+avoides filename clashes.
+
+.. danger::
+
+    Do not manually move your files in the media folder. Paperless remembers the
+    last filename a document was stored as. If you do rename a file, paperless will
+    report your files as missing and won't be able to find them.
+
+Paperless provides the following placeholders withing filenames:
+
+* ``{correspondent}``: The name of the correspondent, or "none".
+* ``{title}``: The title of the document.
+* ``{created}``: The full date and time the document was created.
+* ``{created_year}``: Year created only.
+* ``{created_month}``: Month created only (number 1-12).
+* ``{created_day}``: Day created only (number 1-31).
+* ``{added}``: The full date and time the document was added to paperless.
+* ``{added_year}``: Year added only.
+* ``{added_month}``: Month added only (number 1-12).
+* ``{added_day}``: Day added only (number 1-31).
+* ``{tags}``: I don't know how this works. Look at the source.
+
+Paperless will convert all values for the placeholders into values which are safe
+for use in filenames.
+
+.. hint::
+
+    Paperless checks the filename of a document whenever it is saved. Therefore,
+    you need to update the filenames of your documents and move them after altering
+    this setting by invoking the :ref:`document renamer <utilities-renamer>`.
+
+.. warning::
+
+    Make absolutely sure you get the spelling of the placeholders right, or else
+    paperless will use the default naming scheme instead.
+
+.. caution::
+
+    As of now, you could totally tell paperless to store your files anywhere outside
+    the media directory by setting
+
+    .. code::
+
+        PAPERLESS_FILENAME_FORMAT=../../my/custom/location/{title}
+    
+    However, keep in mind that inside docker, if files get stored outside of the
+    predefined volumes, they will be lost after a restart of paperless.