major docs update

Author: maxtepkeev

docs/changelog.rst

@@ -1,14 +1,28 @@
 Changelog
 =========
 
-0.3.2 (2014-0X-XX)
+0.4.0 (2014-02-XX)
 ------------------
 
 - Added: New exceptions:
 
   * ConflictError
   * ReadonlyAttrError
 
+- Added: Update functionality via update() and save() methods for resources (see docs
+  for details):
+
+  * WikiPage
+  * Project
+
+- Added: Allow to create resources in alternative way via new() method (see docs for
+  details)
+- Added: Allow daterange TimeEntry resource filtering via ``from_date`` and ``to_date``
+  keyword arguments (thanks to `Antoni Aloy <https://github.com/aaloy>`_)
+- Fixed: `Issue #2 <https://github.com/maxtepkeev/python-redmine/issues/2>`_ (limit/offset
+  as keyword arguments were broken)
+- Changed: Documentation for resources rewritten from scratch to be more understandable
+
 0.3.1 (2014-01-23)
 ------------------
 
@@ -20,7 +34,7 @@ Changelog
 0.3.0 (2014-01-18)
 ------------------
 
-- Added: Delete functionality for resources via delete method (see docs for details):
+- Added: Delete functionality via delete() method for resources (see docs for details):
 
   * User
   * Group
@@ -48,7 +62,7 @@ Changelog
   * ResourceNoFieldsProvidedError
   * ResourceNotFoundError
 
-- Added: Create functionality for resources via create method (see docs for details):
+- Added: Create functionality via create() method for resources (see docs for details):
 
   * User
   * Group

docs/operations.rst

@@ -10,31 +10,53 @@ support the requested operation, an exception will be thrown.
 Create
 ------
 
-Resources can be created via ``create`` method. Each resource supports different keyword
-arguments. Unfortunately Redmine doesn't support the creation of some resources via REST
-API. You can read more about it in each resource's documentation.
+Python Redmine provides 2 create operation methods: ``create`` and ``new``. Unfortunately Redmine
+doesn't support the creation of some resources via REST API. You can read more about it in each
+resource's documentation.
+
+create
+++++++
+
+Creates new resource with given fields and saves it to the Redmine.
 
 .. code-block:: python
 
     >>> project = redmine.project.create(name='Vacation', identifier='vacation', description='foo', homepage='http://foo.bar', is_public=True, parent_id=345, inherit_members=True, custom_field_values={2: 'foobar'})
     >>> project
     <redmine.resources.Project #123 "Vacation">
 
+new
++++
+
+Creates new empty resource but doesn't save it to the Redmine. This is useful if you want to
+set some resource fields later based on some condition(s) and only after that save it to the
+Redmine.
+
+.. code-block:: python
+
+    >>> project = redmine.project.new()
+    >>> project.name = 'Vacation'
+    >>> project.identifier = 'vacation'
+    >>> project.description = 'foo'
+    >>> project.is_public = True
+    >>> project.inherit_members = True
+    >>> project.save()
+    True
+
 Read
 ----
 
 Python Redmine provides 3 read operation methods: ``get``, ``all`` and ``filter``. Each
 of this methods support different keyword arguments depending on the resource used and
 method called. You can read more about it in each resource's documentation.
 
-Get
+get
 +++
 
 Returns requested Resource object either by integer ``id`` or by string ``identifier``:
 
 .. code-block:: python
 
-    >>> redmine = Redmine('http://demo.redmine.org')
     >>> project = redmine.project.get('vacation')
     >>> project.name
     'Vacation'
@@ -69,26 +91,24 @@ Returns requested Resource object either by integer ``id`` or by string ``identi
 
         redmine.project.get('vacation').refresh()
 
-All
+all
 +++
 
 Returns a ResourceSet object that contains all the requested Resource objects:
 
 .. code-block:: python
 
-    >>> redmine = Redmine('http://demo.redmine.org')
     >>> projects = redmine.project.all()
     >>> projects
     <redmine.resultsets.ResourceSet object with Project resources>
 
-Filter
+filter
 ++++++
 
 Returns a ResourceSet object that contains Resource objects filtered by some condition(s):
 
 .. code-block:: python
 
-    >>> redmine = Redmine('http://demo.redmine.org')
     >>> issues = redmine.issue.filter(project_id='vacation')
     >>> issues
     <redmine.resultsets.ResourceSet object with Issue resources>
@@ -143,13 +163,13 @@ Returns a ResourceSet object that contains Resource objects filtered by some con
 
       .. code-block:: python
 
-            length = len(redmine.project.all())
+            len(redmine.project.all())
 
     * **list()**. Force evaluation of a ResourceSet by calling list() on it.
 
       .. code-block:: python
 
-            projects = list(redmine.project.all())
+            list(redmine.project.all())
 
     * **Index**. A ResourceSet is also evaluated when you request some of it's Resources by index.
 
@@ -171,7 +191,7 @@ of some resources via REST API. You can read more about it in each resource's do
 .. code-block:: python
 
     >>> redmine.project.delete(1)
-    >>> True
+    True
 
 .. warning::
 

docs/resources/attachment.rst

@@ -3,44 +3,55 @@ Attachment
 
 Supported by Redmine starting from version 1.3
 
-Create
-------
+Manager
+-------
 
-Not supported by Redmine. Some resources support adding attachments via it's create/update methods, e.g. issue.
+All operations on the attachment resource are provided via it's manager. To get access to it
+you have to call ``redmine.attachment`` where ``redmine`` is a configured redmine object.
+See the :doc:`../configuration` about how to configure redmine object.
+
+Create methods
+--------------
 
-Read
-----
+Not supported by Redmine. Some resources support adding attachments via it's create/update methods, e.g. issue.
 
-Methods
-~~~~~~~
+Read methods
+------------
 
-Get
+get
 +++
 
-Supported keyword arguments: None
+.. py:method:: get(resource_id)
+    :module: redmine.managers.ResourceManager
+    :noindex:
+
+    Returns single attachment resource from the Redmine by it's id.
+
+    :param integer resource_id: (required). Id of the attachment.
+    :return: Attachment resource object
 
 .. code-block:: python
 
     >>> attachment = redmine.attachment.get(76905)
     >>> attachment
     <redmine.resources.Attachment #76905 "1(a).png">
 
-All
+all
 +++
 
 Not supported by Redmine
 
-Filter
+filter
 ++++++
 
 Not supported by Redmine
 
-Update
-------
+Update methods
+--------------
 
 Not supported by Redmine
 
-Delete
-------
+Delete methods
+--------------
 
 Not supported by Redmine

docs/resources/custom_field.rst

@@ -3,44 +3,54 @@ Custom Field
 
 Supported by Redmine starting from version 2.4
 
-Create
-------
+Manager
+-------
 
-Not supported by Redmine
+All operations on the custom field resource are provided via it's manager. To get access to
+it you have to call ``redmine.custom_field`` where ``redmine`` is a configured redmine object.
+See the :doc:`../configuration` about how to configure redmine object.
+
+Create methods
+--------------
 
-Read
-----
+Not supported by Redmine
 
-Methods
-~~~~~~~
+Read methods
+------------
 
-Get
+get
 +++
 
 Not supported by Redmine
 
-All
+all
 +++
 
-Supported keyword arguments: None
+.. py:method:: all()
+    :module: redmine.managers.ResourceManager
+    :noindex:
+
+    Returns all custom field resources from the Redmine.
+
+    :return: ResourceSet object
 
 .. code-block:: python
 
     >>> fields = redmine.custom_field.all()
     >>> fields
     <redmine.resultsets.ResourceSet object with CustomField resources>
 
-Filter
+filter
 ++++++
 
 Not supported by Redmine
 
-Update
-------
+Update methods
+--------------
 
 Not supported by Redmine
 
-Delete
-------
+Delete methods
+--------------
 
 Not supported by Redmine

docs/resources/enumeration.rst

@@ -3,51 +3,62 @@ Enumeration
 
 Supported by Redmine starting from version 2.2
 
-Create
-------
+Manager
+-------
 
-Not supported by Redmine
+All operations on the enumeration resource are provided via it's manager. To get access to
+it you have to call ``redmine.enumeration`` where ``redmine`` is a configured redmine object.
+See the :doc:`../configuration` about how to configure redmine object.
+
+Create methods
+--------------
 
-Read
-----
+Not supported by Redmine
 
-Methods
-~~~~~~~
+Read methods
+------------
 
-Get
+get
 +++
 
 Not supported by Redmine
 
-All
+all
 +++
 
 Not supported by Redmine
 
-Filter
+filter
 ++++++
 
-Supported keyword arguments: None
+.. py:method:: filter(**filters)
+    :module: redmine.managers.ResourceManager
+    :noindex:
+
+    Returns enumeration resources that match the given lookup parameters.
+
+    :param string resource:
+      .. raw:: html
 
-Supported filters:
+          (required). Get enumerations for the requested resource. Available resources are:
 
-* **resource**. Get enumerations for the requested resource. Available resources are:
+      - issue_priorities
+      - time_entry_activities
 
-  - issue_priorities
-  - time_entry_activities
+    :return: ResourceSet object
 
 .. code-block:: python
 
     >>> enumerations = redmine.enumeration.filter(resource='time_entry_activities')
     >>> enumerations
     <redmine.resultsets.ResourceSet object with Enumeration resources>
 
-Update
-------
+Update methods
+--------------
 
 Not supported by Redmine
 
-Delete
-------
+Delete methods
+--------------
 
 Not supported by Redmine