[python][WIP] documentation for ClientV2: done with Project Chroot

python/copr/client_v2/handlers.py

@@ -279,9 +279,13 @@ def get_base_url(self, project, **kwargs):
         return "{}{}".format(self.root_url, project.get_href_by_name("chroots"))
 
     def get_one(self, project, name):
-        """
-        :type project: copr.client_v2.resources.Project
+        """ Retrieves project chroot object.
+
+        :type project: :py:class:`~copr.client_v2.resources.Project`
+        :param project: parent project for the chroot
         :param str name: chroot name
+
+        :rtype: :py:class:`~copr.client_v2.resources.ProjectChroot`
         """
 
         url = "{}/{}".format(self.get_base_url(project), name)
@@ -295,8 +299,12 @@ def get_one(self, project, name):
         )
 
     def get_list(self, project):
-        """
-        :type project: copr.client_v2.resources.Project
+        """ Retrieves project chroot list object.
+
+        :type project: :py:class:`~copr.client_v2.resources.Project`
+        :param project: parent project for the chroot
+
+        :rtype: :py:class:`~copr.client_v2.resources.ProjectChrootList`
         """
         response = self.nc.request(self.get_base_url(project))
         return ProjectChrootList.from_response(
@@ -306,19 +314,29 @@ def get_list(self, project):
         )
 
     def disable(self, project, name):
-        """
-        :type project: copr.client_v2.resources.Project
+        """ Disables one chroot for the project
+
+        :type project: :py:class:`~copr.client_v2.resources.Project`
+        :param project: parent project for the chroot
+
         :param str name: chroot name to disable
         """
         url = "{}/{}".format(self.get_base_url(project), name)
         response = self.nc.request(url, method="DELETE", do_auth=True)
         return OperationResult(self, response)
 
     def enable(self, project, name, buildroot_pkgs=None):
-        """
-        :type project: copr.client_v2.resources.Project
+        """ Enables one chroot for the project
 
-        :rtype:
+        :type project: :py:class:`~copr.client_v2.resources.Project`
+        :param project: parent project for the chroot
+
+        :param str name: chroot name to enable
+
+        :params buildroot_pkgs: packages to add into the buildroot
+        :type buildroot_pkgs: list of str
+
+        :rtype: :py:class:`.OperationResult`
         """
 
         new_entity = ProjectChrootEntity(
@@ -336,7 +354,10 @@ def enable(self, project, name, buildroot_pkgs=None):
     def update(self, project, chroot_entity):
         """
         :type project: copr.client_v2.resources.Project
-        :type chroot_entity: copr.client_v2.entities.ProjectChrootEntity
+        :param chroot_entity: Entity to update
+        :type chroot_entity: :py:class:`.entities.ProjectChrootEntity`
+
+        :rtype: :py:class:`.OperationResult`
         """
         url = "{}/{}".format(self.get_base_url(project), chroot_entity.name)
         response = self.nc.request(

python/copr/client_v2/resources.py

@@ -149,21 +149,21 @@ def update(self):
 
         Shortcut for for :py:meth:`.ProjectHandle.update`
 
-        :rtype: :py:class:`~copr.client_v2.resources.OperationResult`
+        :rtype: :py:class:`.OperationResult`
         """
         return self._handle.update(self._entity)
 
     def delete(self):
         """ Updates project using the current state
 
-        :rtype: :py:class:`~copr.client_v2.resources.OperationResult`
+        :rtype: :py:class:`.OperationResult`
         """
         return self._handle.delete(self.id)
 
     def get_self(self):
         """ Retrieves fresh project object from the service
 
-        :rtype: :py:class:`~copr.client_v2.resources.Project`
+        :rtype: :py:class:`.Project`
         """
         return self._handle.get_one(self.id)
 
@@ -180,15 +180,15 @@ def get_project_chroot(self, name):
         """ Retrieves project chroot object by the given name
 
         :param str name: mock chroot name
-        :rtype: :py:class:`~copr.client_v2.resources.ProjectChroot`
+        :rtype: :py:class:`.ProjectChroot`
         """
         handle = self._handle.get_project_chroots_handle()
         return handle.get_one(self, name)
 
     def get_project_chroot_list(self):
         """ Retrieves project chroots list
 
-        :rtype: :py:class:`~copr.client_v2.resources.ProjectChrootList`
+        :rtype: :py:class:`.ProjectChrootList`
         """
         handle = self._handle.get_project_chroots_handle()
         return handle.get_list(self)
@@ -197,8 +197,10 @@ def enable_project_chroot(self, name):
         """
         Enables given chroot for this project
 
+        Shortcut for for :py:meth:`.ProjectChrootHandle.enable`
+
         :param str name: mock chroot name
-        :rtype: :py:class:`~copr.client_v2.resources.OperationResult`
+        :rtype: :py:class:`.OperationResult`
         """
         handle = self._handle.get_project_chroots_handle()
         return handle.enable(self, name)
@@ -249,9 +251,17 @@ def from_response(cls, handle, data_dict, project, response=None, options=None):
                    response=response, links=links, options=options)
 
     def disable(self):
+        """ Disables chroot for the bound project
+
+        :rtype: :py:class:`.OperationResult`
+        """
         return self._handle.disable(self._project, self.name)
 
     def update(self):
+        """ Updates chroot with the current entity state
+
+        :rtype: :py:class:`.OperationResult`
+        """
         return self._handle.update(self._project, self._entity)
 
 

python/docs/ClientV2.rst

@@ -30,7 +30,6 @@ Resources info
     client_v2/resource_info/build.rst
     client_v2/resource_info/mock_chroot.rst
 
-
 Autodoc
 -------
 
@@ -39,3 +38,4 @@ Autodoc
     client_v2/general.rst
     client_v2/handlers.rst
     client_v2/resources.rst
+    client_v2/entities.rst

python/docs/client_v2/entities.rst

@@ -0,0 +1,10 @@
+Entities
+========
+
+Represents domain objects like project or build.
+The user of ``python-copr`` is not expected to use the directly.
+
+.. automodule:: copr.client_v2.entities
+    :members:
+    :undoc-members:
+    :show-inheritance:

python/docs/client_v2/handlers.rst

@@ -1,18 +1,31 @@
 Handlers
 ========
 
+Project
+-------
 .. autoclass:: copr.client_v2.handlers.ProjectHandle
    :members: get_list, get_one, update, delete
-   :undoc-members:
 
+Project chroot
+--------------
 .. autoclass:: copr.client_v2.handlers.ProjectChrootHandle
-   :members: get_list, get_one
-   :undoc-members:
+   :members: get_list, get_one, enable, update, disable
 
 
+Build
+-----
 .. autoclass:: copr.client_v2.handlers.BuildHandle
    :members:
 
+Build task
+----------
+
+.. note::
+   Not implemented yet
+
+
+Mock chroot
+-----------
 .. autoclass:: copr.client_v2.handlers.MockChrootHandle
    :members: get_list, get_one
    :undoc-members:

python/docs/client_v2/resource_info/project.rst

@@ -1,13 +1,18 @@
+
+.. _project-info:
+
 Project
 =======
 
-Access to project resources is done through :py:meth:`~copr.client_v2.client.CoprClient.projects`.
+Access to the projects is done through :py:meth:`~copr.client_v2.client.CoprClient.projects`.
 property of initialized :py:class:`~copr.client_v2.client.CoprClient`. That property is an instance of
 :py:class:`~copr.client_v2.handlers.ProjectHandle`. Projects are represented by
 :py:class:`~copr.client_v2.resources.Project` class.
 
-Individual Attributes
----------------------
+.. _project-attributes:
+
+Project entity attributes
+-------------------------
 
 .. copied from frontend docs, don't forget to update
 
@@ -34,6 +39,19 @@ repos               list of string       yes       list of additional repositori
     all following examples assume that we use ``cl``
     as an instance of :py:class:`.client_v2.client.CoprClient`
 
+
+Get projects list
+-----------------
+
+.. sourcecode:: python
+
+    >>> plist_1 = cl.project.get_list(limit=10)
+    # filter by name
+    >>> plist_2 = cl.project.get_list(name="copr")
+    # search by string
+    >>> plist_2 = cl.project.get_list(name="copr")
+
+
 Get one project
 ---------------
 
@@ -62,18 +80,6 @@ Create new project
 .. note:: Not Implemented yet
 
 
-Fetch projects
---------------
-
-.. sourcecode:: python
-
-    >>> plist_1 = cl.project.get_list(limit=10)
-    # filter by name
-    >>> plist_2 = cl.project.get_list(name="copr")
-    # search by string
-    >>> plist_2 = cl.project.get_list(name="copr")
-
-
 Access project chroots
 ----------------------
 .. note::

python/docs/client_v2/resource_info/project_chroot.rst

@@ -4,6 +4,80 @@
 Project chroot
 ==============
 
-foobar
+Access to the project chroots is done through :py:meth:`~copr.client_v2.client.CoprClient.project_chroots`.
+property of initialized :py:class:`~copr.client_v2.client.CoprClient`. That property is an instance of
+:py:class:`~copr.client_v2.handlers.ProjectChrootHandle`.
+
+However it's usually more convenient to access project chroots
+from an instance of :py:class:`~copr.client_v2.resources.Project`
+using methods :py:meth:`~copr.client_v2.resources.Project.get_project_chroot_list` or
+:py:meth:`~copr.client_v2.resources.Project.get_project_chroot`.
+
+Chroot are represented by
+:py:class:`~copr.client_v2.resources.ProjectChroot` class.
+
+.. _project-chroot-attributes:
+
+Entity Attributes
+-----------------
+
+.. copied from frontend docs, don't forget to update
+
+==================  ==================== ========= ===============
+Field               Type                 Can edit? Description
+==================  ==================== ========= ===============
+name                string               no        chroot name
+buildroot_pkgs      list of strings      yes       packages to be installed into the buildroot
+comps               string               yes       content of the `comps.xml`_
+comps_name          string               yes       name of the uploaded comps file
+comps_len           int                  no        size of the uploaded comps file (bytes)
+==================  ==================== ========= ===============
+
+.. note::
+    all following examples assume that we use ``cl``
+    as an instance of :py:class:`.client_v2.client.CoprClient`
+    and ``p`` as an instance of :py:class:`~copr.client_v2.resources.Project`
+
+Get project chroots list
+------------------------
+
+.. sourcecode:: python
+
+    >>> pc_list = cl.project_chroots.get_list(project=p)
+    # or more simple
+    >>> pc_list = p.get_project_chroot_list()
+    >>>  map(str, pc_list)
+    ['<Project chroot: fedora-21-x86_64, additional packages: [], comps size if any: 0>',
+     '<Project chroot: epel-7-x86_64, additional packages: [], comps size if any: 0>']
+
+
+Get one project chroot
+----------------------
+
+.. sourcecode:: python
+
+
+    >>> pc = cl.project_chroots.get_one(project=p, name="fedora-23-x86_64")
+    # or
+    >>> pc = p.get_project_chroot("fedora-23-x86_64")
+    >>> print(pc)
+    <Project chroot: fedora-23-x86_64, additional packages: [], comps size if any: 0>
+
+Modify project chroot
+---------------------
+
+.. sourcecode:: python
+
+    >>> pc.buildroot_pkgs = ["scl-utils",]
+    >>> pc.update()
+
+Disable project chroot
+----------------------
+.. sourcecode:: python
+
+    >>> pc.disable()
+
+
+.. _comps.xml: https://fedorahosted.org/comps/
 
 

python/docs/client_v2/resources.rst

@@ -1,28 +1,42 @@
 Resources
 =========
 
+Project
+-------
+see entity attributes here: :ref:`project-attributes`.
+
 .. autoclass:: copr.client_v2.resources.Project
    :members:
 
 .. autoclass:: copr.client_v2.resources.ProjectList
    :members:
 
+Project chroot
+--------------
 .. autoclass:: copr.client_v2.resources.ProjectChroot
    :members:
 
-
 .. autoclass:: copr.client_v2.resources.ProjectChrootList
    :members:
 
+Build
+-----
+.. autoclass:: copr.client_v2.resources.Build
+   :members:
 
-.. autoclass:: copr.client_v2.resources.MockChroot
+.. autoclass:: copr.client_v2.resources.BuildList
    :members:
 
+Mock chroot
+-----------
+.. autoclass:: copr.client_v2.resources.MockChroot
+   :members:
 
 .. autoclass:: copr.client_v2.resources.MockChrootList
    :members:
 
-
+Operation result
+----------------
 .. autoclass:: copr.client_v2.resources.OperationResult
    :members: