Merge pull request #73 from spacetelescope/api-doc-fixes

Api doc fixes
spacetelescope · May 4, 2018 · 767d185 · 767d185
2 parents e025a88 + 06c57fe
commit 767d185
Show file tree

Hide file tree

Showing 11 changed files with 167 additions and 133 deletions.
diff --git a/docs/source/api_docs.rst b/docs/source/api_docs.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -74,10 +74,14 @@
 # Usually you set "language" from the command line for these cases.
 language = None
 
+# This is a fix for warnings because of sphinx-autodoc interaction for classes, however it removes
+# method table from the docs.
+numpydoc_show_class_members = False
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = []
+exclude_patterns = ['api/*.rst']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -86,6 +90,7 @@
 todo_include_todos = False
 
 
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -9,7 +9,7 @@ Welcome to jwql's documentation!
 General JWQL description here.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
 API documentation
@@ -19,7 +19,10 @@ API documentation
    :maxdepth: 1
    :caption: Contents:
 
-   api_docs.rst	     
+   permissions.rst
+   preview_image.rst
+   utils.rst
+   tests.rst
 
 
 Indices and tables

diff --git a/docs/source/permissions.rst b/docs/source/permissions.rst
@@ -0,0 +1,7 @@
+***********
+permissions
+***********
+
+.. automodule:: jwql.permissions.permissions
+    :members:
+    :undoc-members:
diff --git a/docs/source/preview_image.rst b/docs/source/preview_image.rst
@@ -0,0 +1,7 @@
+*************
+preview_image
+*************
+
+.. automodule:: jwql.preview_image.preview_image
+    :members:
+    :undoc-members:
diff --git a/docs/source/tests.rst b/docs/source/tests.rst
@@ -0,0 +1,6 @@
+*****
+tests
+*****
+
+.. automodule:: jwql.tests.test_permissions
+    :members:
diff --git a/docs/source/utils.rst b/docs/source/utils.rst
@@ -0,0 +1,6 @@
+*****
+utils
+*****
+
+.. automodule:: jwql.utils.utils
+    :members:
diff --git a/jwql/permissions/permissions.py b/jwql/permissions/permissions.py
@@ -1,13 +1,13 @@
 #! /usr/bin/env python
-"""Permissions module for managing file permissions for jwql.
+"""Permissions module for managing file permissions for ``jwql``.
 
-This module provides jwql with functions to inspect and set file
+This module provides ``jwql`` with functions to inspect and set file
 permissions.
 
-The module takes as input a path to a file or directory, checks
- whether the owner of the file is the jwql admin account, and if
- so, (1) set the permissions appropriately, and (2) set the
- group membership appropriately.
+The module takes as input a path to a file or directory, checks whether
+the owner of the file is the ``jwql`` admin account, and if so, (1) set
+the permissions appropriately, and (2) set the group membership
+appropriately.
 
 Authors
 -------
@@ -20,51 +20,56 @@
     This module can be imported and used with
 
     ::
+
         from jwql.permissions import permissions
         permissions.set_permissions(pathname)
 
     Required arguments:
 
-    ``pathname`` - Directory or file for which the default permissions should be set
+    ``pathname`` - Directory or file for which the default permissions
+    should be set
 
 Notes
 -----
-    Permissions are set and read using the stat module,
-    see https://docs.python.org/3/library/stat.html
-    Below is a list with the relevant stat attribute names,
-    integer, octal, and string representations.
-
-    stat_key stat_mode stat_mode_octal stat_mode_string
-    -------- --------- --------------- ----------------
-    S_IFPORT         0             0o0       ?---------
-    S_IFDOOR         0             0o0       ?---------
-     S_IXOTH         1             0o1       ?--------x
-     S_IWOTH         2             0o2       ?-------w-
-     S_IROTH         4             0o4       ?------r--
-     S_IRWXO         7             0o7       ?------rwx
-     S_IXGRP         8            0o10       ?-----x---
-     S_IWGRP        16            0o20       ?----w----
-     S_IRGRP        32            0o40       ?---r-----
-     S_IRWXG        56            0o70       ?---rwx---
-     S_IEXEC        64           0o100       ?--x------
-     S_IXUSR        64           0o100       ?--x------
-     S_IWUSR       128           0o200       ?-w-------
-    S_IWRITE       128           0o200       ?-w-------
-     S_IREAD       256           0o400       ?r--------
-     S_IRUSR       256           0o400       ?r--------
-     S_IRWXU       448           0o700       ?rwx------
-     S_ISVTX       512          0o1000       ?--------T
-     S_ISGID      1024          0o2000       ?-----S---
-     S_ISUID      2048          0o4000       ?--S------
-     S_IFIFO      4096             0o0       p---------
-     S_IFCHR      8192             0o0       c---------
-     S_IFDIR     16384             0o0       d---------
-     S_IFBLK     24576             0o0       b---------
-     S_IFREG     32768             0o0       ----------
-     S_IFLNK     40960             0o0       l---------
-    S_IFSOCK     49152             0o0       s---------
-     S_IFWHT     57344             0o0       w---------
 
+    Permissions are set and read using the stat module, see
+    https://docs.python.org/3/library/stat.html
+
+    Below is a list with the relevant stat attribute names, integer,
+    octal, and string representations.
+
+    ::
+
+        stat_key stat_mode stat_mode_octal stat_mode_string
+        -------- --------- --------------- ----------------
+        S_IFPORT         0             0o0       ?---------
+        S_IFDOOR         0             0o0       ?---------
+         S_IXOTH         1             0o1       ?--------x
+         S_IWOTH         2             0o2       ?-------w-
+         S_IROTH         4             0o4       ?------r--
+         S_IRWXO         7             0o7       ?------rwx
+         S_IXGRP         8            0o10       ?-----x---
+         S_IWGRP        16            0o20       ?----w----
+         S_IRGRP        32            0o40       ?---r-----
+         S_IRWXG        56            0o70       ?---rwx---
+         S_IEXEC        64           0o100       ?--x------
+         S_IXUSR        64           0o100       ?--x------
+         S_IWUSR       128           0o200       ?-w-------
+        S_IWRITE       128           0o200       ?-w-------
+         S_IREAD       256           0o400       ?r--------
+         S_IRUSR       256           0o400       ?r--------
+         S_IRWXU       448           0o700       ?rwx------
+         S_ISVTX       512          0o1000       ?--------T
+         S_ISGID      1024          0o2000       ?-----S---
+         S_ISUID      2048          0o4000       ?--S------
+         S_IFIFO      4096             0o0       p---------
+         S_IFCHR      8192             0o0       c---------
+         S_IFDIR     16384             0o0       d---------
+         S_IFBLK     24576             0o0       b---------
+         S_IFREG     32768             0o0       ----------
+         S_IFLNK     40960             0o0       l---------
+        S_IFSOCK     49152             0o0       s---------
+         S_IFWHT     57344             0o0       w---------
 """
 
 import grp
@@ -80,7 +85,7 @@
 DEFAULT_MODE = stat.S_IRWXU | stat.S_IRGRP  # equivalent to '?rwxr-----'
 
 def get_group_string(pathname):
-    """Return the group of pathname in string representation.
+    """Return the group of ``pathname`` in string representation.
 
     Parameters
     ----------
@@ -91,7 +96,6 @@ def get_group_string(pathname):
     -------
     group_name : str
         String representation of the group.
-
     """
     file_statinfo = os.stat(pathname)
     groupinfo = grp.getgrgid(file_statinfo.st_gid)
@@ -100,7 +104,7 @@ def get_group_string(pathname):
 
 
 def get_owner_string(pathname):
-    """Return the owner of pathname in string representation.
+    """Return the owner of ``pathname`` in string representation.
 
     Parameters
     ----------
@@ -111,7 +115,6 @@ def get_owner_string(pathname):
     -------
     owner_name : str
         String representation of the owner.
-
     """
     file_statinfo = os.stat(pathname)
     ownerinfo = pwd.getpwuid(file_statinfo.st_uid)
@@ -120,7 +123,7 @@ def get_owner_string(pathname):
 
 
 def has_permissions(pathname, owner=DEFAULT_OWNER, mode=DEFAULT_MODE, group=DEFAULT_GROUP):
-    """Return boolean indicating whether pathname has the specified
+    """Return boolean indicating whether ``pathname`` has the specified
     owner, permission, and group scheme.
 
     Parameters
@@ -131,14 +134,13 @@ def has_permissions(pathname, owner=DEFAULT_OWNER, mode=DEFAULT_MODE, group=DEFA
         String representation of the owner
     mode : int
         Integer representation of the permission mode, compatible
-        with os.stat output
+        with ``os.stat`` output
     group : str
         String representation of the group
 
     Returns
     -------
     boolean : bool
-
     """
     verify_path(pathname)
     file_statinfo = os.stat(pathname)
@@ -158,7 +160,8 @@ def has_permissions(pathname, owner=DEFAULT_OWNER, mode=DEFAULT_MODE, group=DEFA
 
 
 def set_permissions(pathname, owner=DEFAULT_OWNER, mode=DEFAULT_MODE, group=DEFAULT_GROUP, verbose=True):
-    """Set mode and group of the file/directory identfied by pathname, if and only if it is owned by owner.
+    """Set mode and group of the file/directory identfied by
+    ``pathname``, if and only if it is owned by ``owner``.
 
     Parameters
     ----------
@@ -167,12 +170,12 @@ def set_permissions(pathname, owner=DEFAULT_OWNER, mode=DEFAULT_MODE, group=DEFA
     owner : str
         String representation of the owner
     mode : int
-        Integer representation of the permission mode, compatible with os.stat output
+        Integer representation of the permission mode, compatible with
+        ``os.stat`` output
     group : str
         String representation of the group
     verbose : bool
         Boolean indicating whether verbose output is requested
-
     """
     if verbose:
         print('\nBefore:')
@@ -190,13 +193,13 @@ def set_permissions(pathname, owner=DEFAULT_OWNER, mode=DEFAULT_MODE, group=DEFA
 
 
 def show_permissions(pathname):
-    """Verbose output showing group, user, and permission information for a directory or file.
+    """Verbose output showing group, user, and permission information
+    for a directory or file.
 
     Parameters
     ----------
-    pathname: str
+    pathname : str
         Directory or file to be inspected
-
     """
     verify_path(pathname)
     file_statinfo = os.stat(pathname)
@@ -216,13 +219,13 @@ def show_permissions(pathname):
 
 
 def verify_path(pathname):
-    """Verify that pathname is either a directory or a file. If not, an error is raised.
+    """Verify that pathname is either a directory or a file. If not, an
+    error is raised.
 
     Parameters
     ----------
-    pathname: str
+    pathname : str
         Directory or file to be inspected
-
     """
     if (not os.path.isdir(pathname)) and (not os.path.isfile(pathname)):
         raise NotImplementedError('{} is not a valid path or filename'.format(pathname))