Merge pull request #13 from j4321/docs

Improve docs

Author: j4321

docs/conf.py

@@ -12,9 +12,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
 
 
 # -- Project information -----------------------------------------------------
@@ -39,6 +39,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/documentation.rst

@@ -1,102 +1,31 @@
 Documentation
 =============
 
-Functions
----------
+askopendirname
+--------------
+.. autofunction:: tkfilebrowser.askopendirname
 
-- *askopendirname*
+askopendirnames
+---------------
+.. autofunction:: tkfilebrowser.askopendirnames
 
-    Allow the user to choose a single directory. The absolute path of the
-    chosen directory is returned. If the user cancels, an empty string is
-    returned.
-    
-    Syntax:
-    
-    ::
-        
-        askopendirname(parent=None, title=_("Open"), **kwargs)
-
-- *askopendirnames*
-
-    Allow the user to choose multiple directories. A tuple containing the absolute
-    path of the chosen directories is returned. If the user cancels,
-    an empty tuple is returned.    
-    
-    Syntax:
-    
-    ::
-        
-        askopendirnames(parent=None, title=_("Open"), **kwargs)
-        
-- *skopenfilename*
+askopenfilename
+---------------
+.. autofunction:: tkfilebrowser.askopenfilename
 
-    Allow the user to choose a single file. The absolute path of the
-    chosen file is returned. If the user cancels, an empty string is
-    returned.    
-    
-    Syntax:
-    
-    ::
-        
-        askopenfilename(parent=None, title=_("Open"), **kwargs)
-
-- *askopenfilenames*
+askopenfilenames
+----------------
+.. autofunction:: tkfilebrowser.askopenfilenames
 
-    Allow the user to choose multiple files. A tuple containing the absolute
-    path of the chosen files is returned. If the user cancels,
-    an empty tuple is returned.    
-    
-    Syntax:
-    
-    ::
-    
-        askopenfilenames(parent=None, title=_("Open"), **kwargs)
+asksaveasfilename
+-----------------
+.. autofunction:: tkfilebrowser.asksaveasfilename
 
-- *asksaveasfilename*
 
-    Allow the user to choose a file path. The file may not exist but
-    the path to its directory does. If the file already exists, the user
-    is asked to confirm its replacement.
+FileBrowser
+-----------
 
-    Additional option:
+.. autoclass:: tkfilebrowser.FileBrowser
+    :members:
 
-        defaultext : str (e.g. .png)
-            extension added to filename if none is given (default is none)    
-    
-    Syntax:
-    
-    ::
-        
-        asksaveasfilename(parent=None, title=_("Save As"), **kwargs)
-            
-
-Optional keywords arguments common to all functions
----------------------------------------------------
-
-    parent : Tk or Toplevel instance
-        parent window
-
-    title : str
-        the title of the filebrowser window
-
-    initialdir : str
-        directory whose content is initially displayed
-
-    initialfile : str
-        initially selected item (just the name, not the full path)
-
-    filetypes : list ``[("name", "*.ext1|*.ext2|.."), ...]``
-      only the files of given filetype will be displayed,
-      e.g. to allow the user to switch between displaying only PNG or JPG
-      pictures or dispalying all files:
-      filtypes=[("Pictures", "\*.png|\*.PNG|\*.jpg|\*.JPG'), ("All files", "\*")]
-
-    okbuttontext : str
-        text displayed on the validate button, if None, the
-        default text corresponding to the mode is used (either "Open" or "Save")
-
-    cancelbuttontext : str
-        text displayed on the button that cancels the selection.
-
-    foldercreation : bool
-        enable the user to create new folders if True (default)
+    .. automethod:: __init__

tkfilebrowser/filebrowser.py

@@ -52,20 +52,44 @@ def __init__(self, parent, initialdir="", initialfile="", mode="openfile",
                  foldercreation=True, **kw):
         """
         Create a filebrowser dialog.
-
+        
         Arguments:
-            * initialdir: initial folder whose content is displayed
-            * initialfile: initial selected item (just the name, not the full path)
-            * mode: openfile, opendir or save
-            * multiple_selection (open modes only): boolean, allow to select multiple files,
-            * defaultext (save mode only): extension added to filename if none is given
-            * filetypes: [('name', '*.ext1|*.ext2|..'), ...]
-              show only files of given filetype ("*" for all files)
-            * okbuttontext: text displayed on the validate button, if None, the
-              default text corresponding to the mode is used (either Open or Save)
-            * cancelbuttontext: text displayed on the button that cancels the
-              selection.
-            * foldercreation: enable the user to create new folders if True (default)
+    
+        parent : Tk or Toplevel instance
+            parent window
+
+        title : str
+            the title of the filebrowser window
+
+        initialdir : str
+            directory whose content is initially displayed
+
+        initialfile : str
+            initially selected item (just the name, not the full path)
+            
+        mode : str 
+            kind of dialog: "openfile", "opendir" or "save"
+        
+        multiple_selection : bool
+            whether to allow multiple items selection (open modes only)
+            
+        defaultext : str (e.g. '.png')
+            extension added to filename if none is given (default is none)  
+
+        filetypes : list ``[("name", "*.ext1|*.ext2|.."), ...]``
+          only the files of given filetype will be displayed,
+          e.g. to allow the user to switch between displaying only PNG or JPG
+          pictures or dispalying all files:
+          ``filtypes=[("Pictures", "\*.png|\*.PNG|\*.jpg|\*.JPG'), ("All files", "\*")]``
+
+        okbuttontext : str
+            text displayed on the validate button, default is "Open".
+
+        cancelbuttontext : str
+            text displayed on the button that cancels the selection, default is "Cancel".
+
+        foldercreation : bool
+            enable the user to create new folders if True (default)
         """
         # compatibility with tkinter.filedialog arguments: the parent window is called 'master'
         if 'master' in kw and parent is None: