Fix building the code documentation with sphinx

Updated Sphinx conf and tested with Sphinx 1.2.1 Moved webui gen_gettext script Fixed docstring warning in code Renamed console update-tracker to update_tracker
jaeguly · Feb 20, 2014 · 9290cc1 · 9290cc1
1 parent c64da3c
commit 9290cc1
Show file tree

Hide file tree

Showing 113 changed files with 1,203 additions and 862 deletions.
diff --git a/deluge/config.py b/deluge/config.py
@@ -83,9 +83,11 @@ def prop(func):
 
     The decorated function is expected to return a dictionary
     containing one or more of the following pairs:
+
         fget - function for getting attribute value
         fset - function for setting attribute value
         fdel - function for deleting attribute
+
     This can be conveniently constructed by the locals() builtin
     function; see:
     http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/205183

diff --git a/deluge/core/core.py b/deluge/core/core.py
@@ -891,8 +891,7 @@ def get_free_space(self, path=None):
         """
         Returns the number of free bytes at path
 
-        :param path: the path to check free space at, if None, use the default
-        download location
+        :param path: the path to check free space at, if None, use the default download location
         :type path: string
 
         :returns: the number of free bytes at path

diff --git a/deluge/core/torrent.py b/deluge/core/torrent.py
@@ -647,14 +647,16 @@ def get_files(self):
         """Get the files this torrent contains.
 
         Returns:
-            list of dicts: The files.
+            list of dict: The files.
 
-                [{
+            The format for the file dict::
+
+                {
                     "index": int,
                     "path": str,
                     "size": int,
-                    "offset": int,
-                }]
+                    "offset": int
+                }
         """
         if not self.has_metadata:
             return []
@@ -675,17 +677,19 @@ def get_peers(self):
         A list of peers and various information about them.
 
         Returns:
-            list of dicts: The peers.
+            list of dict: The peers.
+
+            The format for the peer dict::
 
-                [{
+                {
                     "client": str,
                     "country": str,
                     "down_speed": int,
                     "ip": str,
                     "progress": float,
                     "seed": bool,
-                    "up_speed": int,
-                }]
+                    "up_speed": int
+                }
         """
         ret = []
         peers = self.handle.get_peer_info()

diff --git a/deluge/core/torrentmanager.py b/deluge/core/torrentmanager.py
@@ -122,6 +122,7 @@ def __init__(self,
         self.owner = owner
         self.name = name
 
+
 class TorrentManagerState:
     def __init__(self):
         self.torrents = []
@@ -363,7 +364,6 @@ def add(self, torrent_info=None, state=None, options=None, save_state=True,
             options["owner"] = state.owner
             options["name"] = state.name
 
-
             torrent_info = self.get_torrent_info_from_file(
                 os.path.join(self.state_dir, state.torrent_id + ".torrent"))
             if torrent_info:
@@ -1266,7 +1266,7 @@ def torrents_status_update(self, torrent_ids, keys, diff=False):
         :param keys: the keys to get the status on
         :type keys: list of str
         :param diff: if True, will return a diff of the changes since the last
-        call to get_status based on the session_id
+            call to get_status based on the session_id
         :type diff: bool
 
         :returns: a status dictionary for the equested torrents.

diff --git a/deluge/ui/Win32IconImagePlugin.py b/deluge/ui/Win32IconImagePlugin.py
@@ -5,18 +5,18 @@
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at 
+# You may obtain a copy of the License at
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
-# Unless required by applicable law or agreed to in writing, software 
-# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 
-# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 
-# License for the specific language governing permissions and limitations 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
 # under the License.
 #
 # $Id$
 """Alternate PIL plugin for dealing with Microsoft .ico files. Handles XOR
-transparency masks, XP style 8bit alpha channels and Vista style PNG image 
+transparency masks, XP style 8bit alpha channels and Vista style PNG image
 parts.
 
 >>> import PIL.Image
@@ -39,9 +39,9 @@
 
 Example icon to test with `down.ico`_
 
-.. _Image-SIG http://mail.python.org/pipermail/image-sig/2008-May/004986.html
-.. _django snippet http://www.djangosnippets.org/snippets/1287/
-.. _down.ico http://www.axialis.com/tutorials/iw/down.ico
+.. _Image-SIG: http://mail.python.org/pipermail/image-sig/2008-May/004986.html
+.. _django snippet: http://www.djangosnippets.org/snippets/1287/
+.. _down.ico: http://www.axialis.com/tutorials/iw/down.ico
 """
 
 import logging
@@ -85,7 +85,7 @@ def __init__ (self, buf):
           directory[j] = 256
       icon_header = dict(zip(dir_fields, directory))
       icon_header['color_depth'] = (
-          icon_header['bpp'] or 
+          icon_header['bpp'] or
           (icon_header['nb_color'] == 16 and 4))
       icon_header['dim'] = (icon_header['width'], icon_header['height'])
       self.entry.append(icon_header)
@@ -196,7 +196,7 @@ def frame (self, idx):
           w += 32 - (im.size[0] % 32)
         # the total mask data is padded row size * height / bits per char
         total_bytes = long((w * im.size[1]) / 8)
-        log.debug("tot=%d, off=%d, w=%d, size=%d", 
+        log.debug("tot=%d, off=%d, w=%d, size=%d",
             len(data), and_mask_offset, w, total_bytes)
 
         self.buf.seek(and_mask_offset)
@@ -225,7 +225,7 @@ def frame (self, idx):
 
   def __repr__ (self):
     s = 'Microsoft Icon: %d images (max %dx%d %dbpp)' % (
-        len(self.entry), self.entry[0]['width'], self.entry[0]['height'], 
+        len(self.entry), self.entry[0]['width'], self.entry[0]['height'],
         self.entry[0]['bpp'])
     return s
   #end __repr__
@@ -236,10 +236,10 @@ class Win32IconImageFile (PIL.ImageFile.ImageFile):
   """
   PIL read-only image support for Microsoft .ico files.
 
-  By default the largest resolution image in the file will be loaded. This can 
+  By default the largest resolution image in the file will be loaded. This can
   be changed by altering the 'size' attribute before calling 'load'.
 
-  The info dictionary has a key 'sizes' that is a list of the sizes available 
+  The info dictionary has a key 'sizes' that is a list of the sizes available
   in the icon file.
 
   Handles classic, XP and Vista icon formats.

diff --git a/deluge/ui/console/commands/update-tracker.py → deluge/ui/console/commands/update_tracker.py b/deluge/ui/console/commands/update-tracker.py → deluge/ui/console/commands/update_tracker.py
@@ -43,7 +43,7 @@
 
 class Command(BaseCommand):
     """Update tracker for torrent(s)"""
-    usage = "Usage: update-tracker [ * | <torrent-id> [<torrent-id> ...] ]"
+    usage = "Usage: update_tracker [ * | <torrent-id> [<torrent-id> ...] ]"
     aliases = ['reannounce']
 
     def handle(self, *args, **options):
@@ -53,7 +53,7 @@ def handle(self, *args, **options):
             return
         if len(args) > 0 and args[0].lower() == '*':
             args = [""]
-            
+
         torrent_ids = []
         for arg in args:
             torrent_ids.extend(self.console.match_torrent(arg))

diff --git a/deluge/ui/gtkui/path_combo_chooser.py b/deluge/ui/gtkui/path_combo_chooser.py
@@ -249,8 +249,8 @@ def handle_list_scroll(self, next=None, path=None, set_entry=False, swap=False,
         """
         Handles changes to the row selection.
 
-        :param next: the direction to change selection. None means no change. True means down
-        and False means up.
+        :param next: the direction to change selection. True means down and False means up.
+            None means no change.
         :type  next: boolean/None
         :param path: the current path. If None, the currently selected path is used.
         :type  path: tuple

diff --git a/deluge/ui/gtkui/preferences.py b/deluge/ui/gtkui/preferences.py
@@ -535,8 +535,7 @@ def set_config(self, hide=False):
         """
         Sets all altered config values in the core.
 
-        :param hide: bool, if True, will not re-show the dialog and will hide
-        it instead
+        :param hide: bool, if True, will not re-show the dialog and will hide it instead
         """
         try:
             from hashlib import sha1 as sha_hash

diff --git a/deluge/ui/tracker_icons.py b/deluge/ui/tracker_icons.py
@@ -555,7 +555,7 @@ def url_to_host(url):
     :param url: the URL in question
     :type url: string
     :returns: the host of the given URL
-    :rtype:string
+    :rtype: string
     """
     return urlparse(url).hostname
 
@@ -569,6 +569,7 @@ def host_to_icon_name(host, mimetype):
     :type mimetype: string
     :returns: the icon's filename
     :rtype: string
+
     """
     return host+'.'+mimetype_to_extension(mimetype)
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,7 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# deluge documentation build configuration file, created by
-# sphinx-quickstart on Tue Nov  4 18:24:06 2008.
+# Deluge documentation build configuration file
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
@@ -13,18 +12,49 @@
 
 import sys, os
 import deluge.common
+from version import get_version
+from datetime import date
 
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
-sys.path.append(os.path.abspath(os.path.dirname(__file__ + "../../")))
+sys.path.append(os.path.abspath(os.path.dirname(__file__ + '../../')))
+
+class Mock(object):
+
+    __all__ = []
+
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def __call__(self, *args, **kwargs):
+        return Mock()
+
+    @classmethod
+    def __getattr__(cls, name):
+        if name in ('__file__', '__path__'):
+            return '/dev/null'
+        elif name[0] == name[0].upper():
+            mockType = type(name, (), {})
+            mockType.__module__ = __name__
+            return mockType
+        else:
+            return Mock()
+
+MOCK_MODULES = ['deluge.ui.languages', 'deluge.ui.countries', 'deluge.ui.gtkui.gtkui',
+                'deluge.libtorrent', 'psyco', 'rencode', 'win32file', 'win32event',
+                'win32gui', 'win32api', 'win32con', '_winreg']
+
+for mod_name in MOCK_MODULES:
+    sys.modules[mod_name] = Mock()
+
 
 # General configuration
 # ---------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinxcontrib.napoleon']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -37,20 +67,17 @@
 
 # General substitutions.
 project = 'Deluge'
-copyright = '2008-2010, Deluge Team'
+current_year = date.today().year
+copyright = '2008-%s, Deluge Team' % current_year
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
 #
 
-def find_version():
-    f = open("../../setup.py", "r")
-    for line in f:
-        if " version = " in line:
-            return line.strip().replace("\"", "").replace(" ", "").replace(",", "").split("=")[1]
-
 # The short X.Y version.
-version = find_version()
+version = get_version(prefix='deluge-', suffix='.dev0')
+# remove the created file by get_version
+os.remove('RELEASE-VERSION')
 # The full version, including alpha/beta/rc tags.
 release = version
 
@@ -66,6 +93,7 @@ def find_version():
 # List of directories, relative to source directories, that shouldn't be searched
 # for source files.
 #exclude_dirs = []
+exclude_pattern = ['deluge/_libtorrent.py', 'deluge/__rpcapi.py']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -112,7 +140,7 @@ def find_version():
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -2,14 +2,14 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Deluge's documentation!
+Welcome to Deluge's Documentation!
 ==================================
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
-   
+
    Core <core/index.rst>
    Interfaces <interfaces/index.rst>
 
@@ -28,6 +28,3 @@ Modules
    :glob:
 
    modules/*
-   modules/*/*
-   modules/*/*/*
-   modules/*/*/*/*
diff --git a/docs/source/modules/__rpcapi.rst b/docs/source/modules/__rpcapi.rst
diff --git a/docs/source/modules/_libtorrent.rst b/docs/source/modules/_libtorrent.rst
diff --git a/docs/source/modules/bencode.rst b/docs/source/modules/bencode.rst
diff --git a/docs/source/modules/common.rst b/docs/source/modules/common.rst
diff --git a/docs/source/modules/component.rst b/docs/source/modules/component.rst