Refactor fs.appfs to avoid copying __init__ documentation

Author: althonos

docs/source/conf.py

@@ -304,3 +304,14 @@
 #texinfo_no_detailmenu = False
 
 napoleon_include_special_with_doc = True
+
+
+# -- Options for autodoc -----------------------------------------------------
+
+# Configure autodoc so that it doesn't skip building the documentation for
+# __init__ methods, since the arguments to instantiate classes should be in
+# the __init__ docstring and not at the class-level.
+
+autodoc_default_options = {
+    'special-members': '__init__',
+}

fs/appfs.py

@@ -9,8 +9,11 @@
 
 # see http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx
 
+import abc
 import typing
 
+import six
+
 from .osfs import OSFS
 from ._repr import make_repr
 from appdirs import AppDirs
@@ -29,6 +32,22 @@
 ]
 
 
+class _CopyInitMeta(abc.ABCMeta):
+    """A metaclass that performs a hard copy of the `__init__`.
+
+    This is a fix for Sphinx, which is a pain to configure in a way that
+    it documents the ``__init__`` method of a class when it is inherited.
+    Copying ``__init__`` makes it think it is not inherited, and let us
+    share the documentation between all the `_AppFS` subclasses.
+
+    """
+
+    def __new__(mcls, classname, bases, cls_dict):
+        cls_dict.setdefault("__init__", bases[0].__init__)
+        return super().__new__(mcls, classname, bases, cls_dict)
+
+
+@six.add_metaclass(_CopyInitMeta)
 class _AppFS(OSFS):
     """Abstract base class for an app FS."""
 
@@ -46,6 +65,19 @@ def __init__(
         create=True,  # type: bool
     ):
         # type: (...) -> None
+        """Create a new application-specific filesystem.
+
+        Arguments:
+            appname (str): The name of the application.
+            author (str): The name of the author (used on Windows).
+            version (str): Optional version string, if a unique location
+                per version of the application is required.
+            roaming (bool): If `True`, use a *roaming* profile on
+                Windows.
+            create (bool): If `True` (the default) the directory
+                will be created if it does not exist.
+
+        """
         self.app_dirs = AppDirs(appname, author, version, roaming)
         self._create = create
         super(_AppFS, self).__init__(
@@ -76,16 +108,6 @@ class UserDataFS(_AppFS):
     May also be opened with
     ``open_fs('userdata://appname:author:version')``.
 
-    Arguments:
-        appname (str): The name of the application.
-        author (str): The name of the author (used on Windows).
-        version (str): Optional version string, if a unique location
-            per version of the application is required.
-        roaming (bool): If `True`, use a *roaming* profile on
-            Windows.
-        create (bool): If `True` (the default) the directory
-            will be created if it does not exist.
-
     """
 
     app_dir = "user_data_dir"
@@ -97,16 +119,6 @@ class UserConfigFS(_AppFS):
     May also be opened with
     ``open_fs('userconf://appname:author:version')``.
 
-    Arguments:
-        appname (str): The name of the application.
-        author (str): The name of the author (used on Windows).
-        version (str): Optional version string, if a unique location
-            per version of the application is required.
-        roaming (bool): If `True`, use a *roaming* profile on
-            Windows.
-        create (bool): If `True` (the default) the directory
-            will be created if it does not exist.
-
     """
 
     app_dir = "user_config_dir"
@@ -118,16 +130,6 @@ class UserCacheFS(_AppFS):
     May also be opened with
     ``open_fs('usercache://appname:author:version')``.
 
-    Arguments:
-        appname (str): The name of the application.
-        author (str): The name of the author (used on Windows).
-        version (str): Optional version string, if a unique location
-            per version of the application is required.
-        roaming (bool): If `True`, use a *roaming* profile on
-            Windows.
-        create (bool): If `True` (the default) the directory
-            will be created if it does not exist.
-
     """
 
     app_dir = "user_cache_dir"
@@ -139,16 +141,6 @@ class SiteDataFS(_AppFS):
     May also be opened with
     ``open_fs('sitedata://appname:author:version')``.
 
-    Arguments:
-        appname (str): The name of the application.
-        author (str): The name of the author (used on Windows).
-        version (str): Optional version string, if a unique location
-            per version of the application is required.
-        roaming (bool): If `True`, use a *roaming* profile on
-            Windows.
-        create (bool): If `True` (the default) the directory
-            will be created if it does not exist.
-
     """
 
     app_dir = "site_data_dir"
@@ -160,16 +152,6 @@ class SiteConfigFS(_AppFS):
     May also be opened with
     ``open_fs('siteconf://appname:author:version')``.
 
-    Arguments:
-        appname (str): The name of the application.
-        author (str): The name of the author (used on Windows).
-        version (str): Optional version string, if a unique location
-            per version of the application is required.
-        roaming (bool): If `True`, use a *roaming* profile on
-            Windows.
-        create (bool): If `True` (the default) the directory
-            will be created if it does not exist.
-
     """
 
     app_dir = "site_config_dir"
@@ -181,16 +163,6 @@ class UserLogFS(_AppFS):
     May also be opened with
     ``open_fs('userlog://appname:author:version')``.
 
-    Arguments:
-        appname (str): The name of the application.
-        author (str): The name of the author (used on Windows).
-        version (str): Optional version string, if a unique location
-            per version of the application is required.
-        roaming (bool): If `True`, use a *roaming* profile on
-            Windows.
-        create (bool): If `True` (the default) the directory
-            will be created if it does not exist.
-
     """
 
     app_dir = "user_log_dir"