Documentation

docs/source/authors.rst

@@ -0,0 +1,10 @@
+Authors
+=======
+
+Many thanks to all these people for making ``django-webdav-storage`` better
+
+* Mikhail `marazmiki <https://guthub.com/marazmiki>`_ Porokhovnichenko <marazmiki@gmail.com>
+* Richard `lander2k2 https://github.com/lander2k2`_ Lander <lander2k2@gmail.com>
+* Dmitriy `dimier https://github.com/dimier`_ Narkevich <github@dimier.org>
+* Matvey `subuk https://github.com/subuk`_  Kruglov <kubuzzzz@gmail.com>
+* `fuxter https://github.com/fuxter`_ <fuxterz@gmail.com>

docs/source/base.rst

@@ -0,0 +1,30 @@
+Requirements
+============
+
+* Python ``2.7+``, ``3.4+``, ``3.5+``.
+* Django framework version ``1.7+``
+* Awesome `python-requests <http://docs.python-requests.org/en/master/>`_ library
+
+
+
+.. attention::
+
+    In python 3.x ``ContentFile`` with text mode content (not binary one) will causes ``TypeError`` due `requests <http://docs.python-requests.org/en/master/>`_ restrictions.
+
+
+Installation
+============
+
+You can install the latest stable version of ``django-webdav-storage`` from `PyPI <https://pypi.python.org>`_ within ``pip`` command: ::
+
+    $ pip install django-webdav-storage
+
+or ``easy_install`` one: ::
+
+    $ easy_install django-webdav-storage
+
+If you want install developer version, please use ``pip``: ::
+
+    $ pip install -e git+github.com/marazmiki/django-webdav-storage.git#egg=django-webdav-storage
+
+All dependencies will be installed automatically

docs/source/changelog.rst

@@ -0,0 +1,74 @@
+Change log
+==========
+
+0.6x
+----
+
+0.6.1
+~~~~~
+
+* Cleanup code, remove unused code — thanks to Matvei Kroglov
+
+0.6
+~~~
+
+* Add directory listing feature (if webdav server supports it) — thanks to Matvei Kroglov
+
+0.5x
+----
+
+0.5
+~~~
+
+* Chunked upload support — thanks to Matvei Kroglov
+
+
+0.4x
+----
+
+0.4.2
+~~~~~
+
+* Update django versions
+
+
+0.4.1
+~~~~~
+
+* Update django versions
+
+0.4
+~~~
+
+* Updated head django versions;
+* Support of Django 1.8x;
+* Explicit directory tree creation (MKCOL) now os optional — thanks to Dmitriy Narkevich
+* Added missed self.webdav wrapper for MKCOL request
+
+0.3x
+----
+
+0.3
+~~~
+
+* Updated head django versions;
+* Explicit directory tree creation (MKCOL) — thanks to Richard Lander;
+* Fix set_public_url and set_webdav_url method names — thanks to fuxter;
+* Added AUTHORS.rst and CHANGELOG.rst files
+
+0.2x
+----
+
+0.2
+~~~
+
+* Updated head Django versions.
+
+
+0.1x
+----
+
+0.1
+~~~
+
+* Initial release.

docs/source/configuration.rst

@@ -0,0 +1,58 @@
+Configuration
+=============
+
+Base settings
+-------------
+
+First of all, you need set the your WebDAV server url (``WEBDAV_URL`` setting) and public read-only public url of this if there (``WEBDAV_PUBLIC_URL`` setting)
+
+.. code:: python
+
+    # settings.py
+
+    WEBDAV_URL = "https://my-internal-webdav-server.example.com"
+    WEBDAV_PUBLIC_URL = "http://my-awesome-public-webdav-server.example.com"
+
+
+If you want use HTTP Basic authorization to WebDAV access, you can specify your credentials like that:
+
+.. code:: python
+
+    WEBDAV_URL = 'http://johndoe:secret@my-internal-webdav-server.example.com'
+
+
+Second, set the ``django_webdav_storage.storage.WebDavStorage`` storage class as default storage class:
+
+.. code:: python
+
+    DEFAULT_FILE_STORAGE = 'django_webdav_storage.storage.WebDavStorage'
+
+If your webdav backend can't recursively create path,  set the ``WEBDAV_RECURSIVE_MKCOL`` variable to ``True`` (please pay attention: `nginx can do this <http://nginx.org/en/docs/http/ngx_http_dav_module.html#create_full_put_path>`_):
+
+
+.. code::  python
+
+    WEBDAV_RECURSIVE_MKCOL = True    # *NOT* required for nginx!
+
+.. attention::
+
+    The ``WEBDAV_RECURSIVE_MKCOL`` setting must be ``False`` if you use nginx as WebDAV service since ``nginx`` allows you automatically create full path to uloaded file when ``create_full_put_path`` is ``on``.
+
+
+List support in nginx
+---------------------
+
+If you use **nginx** as WebDAV server and want to enable storage directory listing, set the ``WEBDAV_LISTING_BACKEND`` option to:
+
+.. code:: python
+
+    WEBDAV_LISTING_BACKEND = 'django_webdav_storage.listing.nginx_autoindex'
+
+Autoindex feature must be enabled in your nginx configuration for application servers (see example below). Be careful! Allowing autoindex for any user may lead to security and performance issues.
+
+Also, you may specify path to other function with the following interface:
+
+.. code:: python
+
+    def listdir(storage_object, path_string):
+        return dirs_list, files_list

docs/source/examples.rst

@@ -0,0 +1,51 @@
+Examples
+========
+
+Add WebDAV support to nginx
+---------------------------
+
+.. code:: nginx
+
+    # Public readonly media server.
+    server {
+        listen 80;
+        charset        utf-8;
+        server_tokens  off;
+        server_name    media.example.com;
+
+        access_log     /var/log/nginx/media_access.log;
+        error_log      /var/log/nginx/media_error.log;
+
+        root           /usr/share/nginx/webdav;
+
+    }
+
+    # WebDAV server
+    server {
+        listen 80;
+        charset        utf-8;
+        server_tokens  off;
+        server_name    webdav.example.com;
+
+        access_log     /var/log/nginx/webdav_access.log;
+        error_log      /var/log/nginx/webdav_error.log;
+
+        root           /usr/share/nginx/webdav;
+
+        client_max_body_size    10m;
+        client_body_temp_path   /tmp;
+        create_full_put_path    on;
+        autoindex               on;
+
+        dav_methods             PUT DELETE MKCOL COPY MOVE;
+        dav_access              user:rw   group:r   all:r;
+
+        satisfy                 any;
+
+        allow                   127.0.0.1/32;
+        deny                    all;
+
+        auth_basic              'My WebDAV area';
+        auth_basic_user_file    /usr/share/nginx/.htpasswd;
+    }
+