Commits

Michael Forbes committed 058fa4f Merge

autodoc -> default

Comments (0)

Files changed (8)

 
    .. versionadded:: 1.0
 
+.. confval:: global_config_file
 
+   If this is specified, then this file will be executed and used to
+   provide default values.  Values in the local config file will
+   overwrite these unless the values are lists or dicts.  For lists
+   the local values will be appended (so they take effect last).  For
+   dict, any local keys will overwrite the global keys.  These
+   defaults are processed after the local :file:`conf.py` is read, so
+   the defaults are not available during the processing of :file:`conf.py`.
+   
+   This is useful if you need to specify site-specific paths
+   etc. however consider that will make it difficult to distribute
+   your documentation because you will need to explicitly include this
+   file.
+   
+   .. versionadded:: sphinx-mmf
+  
 Project information
 -------------------
 

doc/extensions.rst

File contents unchanged.
 import re
 from os import path
 
-from sphinx.errors import ConfigError
+from sphinx.errors import ConfigError, SphinxError
 from sphinx.util.osutil import make_filename
 
 nonascii_re = re.compile(r'[\x80-\xff]')
         needs_sphinx = (None, None),
         nitpicky = (False, 'env'),
 
+        # Global configuration file.
+        global_config_file = (None, 'env'),
+
         # HTML options
         html_theme = ('default', 'html'),
         html_theme_path = ([], 'html'),
             finally:
                 os.chdir(olddir)
 
+        # Add global configurations.  We only do this if the local
+        # config file specifies a global config file.  This way,
+        # documentation that does not use this feature is not
+        # affected.
+        global_config_file = config.get('global_config_file', "")
+        if global_config_file:
+            global_config_file = os.path.abspath(
+                os.path.expanduser(global_config_file))
+            global_config = {}
+            if os.path.isfile(global_config_file):
+                try:
+                    execfile(global_config_file, global_config)
+                except Exception, err:
+                    raise SphinxError("\n".join([
+                        "Error reading global config file %s"
+                        % (global_config_file,),
+                        str(err)]))
+            else:
+                raise SphinxError("Could not read global config file %s"
+                                  % (global_config_file,))
+
+            for k in global_config:
+                v_global = global_config[k]
+                if k in config:
+                    v_local = config[k]
+                    if (isinstance(v_local, dict) and
+                        isinstance(v_global, dict)):
+                        v_global.update(v_local) # Local overrides
+                        config[k] = v_global
+                    elif (isinstance(v_local, list) and
+                          isinstance(v_global, list)):
+                        v_local.extend(     # Locals come first
+                            [v for v in v_global if v not in v_local])
+                    else:                   
+                        pass                     # Locals completely overwrite.
+                else:                       # Set as default
+                    config[k] = v_global
+
         self._raw_config = config
         # these two must be preinitialized because extensions can add their
         # own config values

sphinx/ext/autodoc.py

             # if isattr is True, the member is documented as an attribute
             isattr = False
 
-            if want_all and membername.startswith('_'):
+            if (want_all and (membername.startswith('_') and not
+                              self.options.private_members
+                              or membername.startswith('__'))):
                 # ignore members whose name starts with _ by default
                 skip = True
             elif (namespace, membername) in attr_docs:
         'show-inheritance': bool_option, 'synopsis': identity,
         'platform': identity, 'deprecated': bool_option,
         'member-order': identity, 'exclude-members': members_set_option,
+        'private-members': bool_option,
     }
 
     @classmethod
         'noindex': bool_option, 'inherited-members': bool_option,
         'show-inheritance': bool_option, 'member-order': identity,
         'exclude-members': members_set_option,
+        'private-members': bool_option,        
     }
 
     @classmethod

sphinx/ext/autosummary/__init__.py

         return False
     isgetsetdescriptor = ismemberdescriptor
 
-def get_documenter(obj):
+def get_documenter(obj, mname=''):
     """
     Get an autodoc.Documenter class suitable for documenting the given object
     """

sphinx/ext/autosummary/generate.py

         f = open(fn, 'w')
 
         try:
-            doc = get_documenter(obj)
+            doc = get_documenter(obj, name)
 
             if template_name is not None:
                 template = template_env.get_template(template_name)
             def get_members(obj, typ, include_public=[]):
                 items = [
                     name for name in dir(obj)
-                    if get_documenter(getattr(obj, name)).objtype == typ
+                    if get_documenter(getattr(obj, name), name).objtype == typ
                 ]
                 public = [x for x in items
                           if x in include_public or not x.startswith('_')]
+                if hasattr(obj, '__all__'):
+                    public = [x for x in items if x in obj.__all__]
+                else:
+                    public = [x for x in items
+                              if x in include_public or not x.startswith('_')]
                 return public, items
 
             ns = {}
 
             if doc.objtype == 'module':
                 ns['members'] = dir(obj)
+                ns['modules'], ns['all_modules'] = \
+                               get_members(obj, 'module')
                 ns['functions'], ns['all_functions'] = \
                                    get_members(obj, 'function')
                 ns['classes'], ns['all_classes'] = \

sphinx/ext/autosummary/templates/autosummary/module.rst

 {{ underline }}
 
 .. automodule:: {{ fullname }}
+   :members:
+
+   {% block modules %}
+   {% if modules %}
+   .. rubric:: Modules
+
+   .. autosummary::
+   {% for item in modules %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
 
    {% block functions %}
    {% if functions %}

sphinx/quickstart.py

 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+# Global defaults can be specified in the file named here.  They will
+# be overwritten by locally defined values unless the value is a list
+# or dict in which case the local values will have precedence.
+# Use mainly for local documentation that you do not intend to
+# widely distribute (note etc.)
+#global_config_file = '~/.sphinx.py'
 
 # -- Options for HTML output ---------------------------------------------------