Merge pull request ceph#33911 from tchaikov/wip-cephfs-doc

pybind/cephfs, doc: add python binding doc

Reviewed-by: Josh Durgin <[email protected]>

admin/build-doc

@@ -159,7 +159,7 @@ rm -rf $JAVADIR/doc
 ant -buildfile $JAVADIR/build.xml docs
 
 # Create clean target directory
-JAVA_OUTDIR=$TOPDIR/build-doc/output/html/api/libcephfs-java/javadoc
+JAVA_OUTDIR=$TOPDIR/build-doc/output/html/cephfs/api/libcephfs-java/javadoc
 rm -rf $JAVA_OUTDIR
 mkdir $JAVA_OUTDIR
 

doc/api/index.rst

@@ -14,10 +14,9 @@ See `Ceph Storage Cluster APIs`_.
 Ceph File System APIs
 =====================
 
-See `libcephfs (javadoc)`_.
-
-.. _libcephfs (javadoc): libcephfs-java
+See `libcephfs`_
 
+.. _libcephfs: ../cephfs/api
 
 Ceph Block Device APIs
 ======================

doc/cephfs/api/index.rst

@@ -0,0 +1,9 @@
+============
+ CephFS APIs
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   libcephfs (Java) <libcephfs-java>
+   libcephfs (Python) <libcephfs-py>

doc/cephfs/api/libcephfs-py.rst

@@ -0,0 +1,13 @@
+===================
+ LibCephFS (Python)
+===================
+
+.. highlight:: python
+
+The `cephfs` python module provides access to CephFS service.
+
+API calls
+=========
+
+.. automodule:: cephfs
+    :members: DirEntry, DirResult, LibCephFS

doc/cephfs/index.rst

@@ -184,7 +184,7 @@ Developer Guides
 
     Journaler Configuration <journaler>
     Client's Capabilities <capabilities>
-    libcephfs for Java <../../api/libcephfs-java/>
+    Java and Python bindings <api/index>
     Mantle <mantle>
 
 

src/pybind/cephfs/cephfs.pyx

@@ -891,7 +891,7 @@ cdef class LibCephFS(object):
  
         :param path: the path of the directory to create.  This must be either an
                      absolute path or a relative path off of the current working directory.
-        :param mode the permissions the directory should have once created.
+        :param mode: the permissions the directory should have once created.
         """
 
         self.require_state("mounted")
@@ -909,9 +909,10 @@ cdef class LibCephFS(object):
     def chmod(self, path, mode) :
         """
         Change directory mode.
+
         :param path: the path of the directory to create.  This must be either an
-                    absolute path or a relative path off of the current working directory.
-        :param mode the permissions the directory should have once created.
+                     absolute path or a relative path off of the current working directory.
+        :param mode: the permissions the directory should have once created.
         """
         self.require_state("mounted")
         path = cstr(path, 'path')
@@ -928,6 +929,7 @@ cdef class LibCephFS(object):
     def chown(self, path, uid, gid, follow_symlink=True):
         """
         Change directory ownership
+
         :param path: the path of the directory to change.
         :param uid: the uid to set
         :param gid: the gid to set
@@ -969,7 +971,7 @@ cdef class LibCephFS(object):
 
         :param path: the full path of directories and sub-directories that should
                      be created.
-        :param mode the permissions the directory should have once created
+        :param mode: the permissions the directory should have once created
         """
         self.require_state("mounted")
         path = cstr(path, 'path')
@@ -1073,10 +1075,10 @@ cdef class LibCephFS(object):
         """
         Read data from the file.
  
-        :param fd : the file descriptor of the open file to read from.
-        :param offset : the offset in the file to read from.  If this value is negative, the
-                        function reads from the current offset of the file descriptor.
-        :param l : the flag to indicate what type of seeking to perform
+        :param fd: the file descriptor of the open file to read from.
+        :param offset: the offset in the file to read from.  If this value is negative, the
+                       function reads from the current offset of the file descriptor.
+        :param l: the flag to indicate what type of seeking to perform
         """     
         self.require_state("mounted")
         if not isinstance(offset, int):
@@ -1116,10 +1118,10 @@ cdef class LibCephFS(object):
         """
         Write data to a file.
        
-        :param fd : the file descriptor of the open file to write to
-        :param buf : the bytes to write to the file
-        :param offset : the offset of the file write into.  If this value is negative, the
-                        function writes to the current offset of the file descriptor.
+        :param fd: the file descriptor of the open file to write to
+        :param buf: the bytes to write to the file
+        :param offset: the offset of the file write into.  If this value is negative, the
+                       function writes to the current offset of the file descriptor.
         """
         self.require_state("mounted")
         if not isinstance(fd, int):
@@ -1564,10 +1566,10 @@ cdef class LibCephFS(object):
         """
         Set the file's current position.
  
-        :param fd : the file descriptor of the open file to read from.
-        :param offset : the offset in the file to read from.  If this value is negative, the
-                        function reads from the current offset of the file descriptor.
-        :param whence : the flag to indicate what type of seeking to performs:SEEK_SET, SEEK_CUR, SEEK_END
+        :param fd: the file descriptor of the open file to read from.
+        :param offset: the offset in the file to read from.  If this value is negative, the
+                       function reads from the current offset of the file descriptor.
+        :param whence: the flag to indicate what type of seeking to performs:SEEK_SET, SEEK_CUR, SEEK_END
         """     
         self.require_state("mounted")
         if not isinstance(fd, int):