Ticket #7549: trac_7549-doc_inheritance_underscore.patch

File trac_7549-doc_inheritance_underscore.patch, 7.4 KB (added by mpatel, 12 years ago)

Doc build options for inherited members, private variables. Inheritance diagrams. Apply to sage repo.

  • doc/common/builder.py

    # HG changeset patch
    # User Mitesh Patel <qed777@gmail.com>
    # Date 1259415883 28800
    # Node ID aeff9f2bcb16607b9144bde030102882040e2d74
    # Parent  65120f4410c37862139d83f2dd4476264af5c2c8
    #7549/doc: Inheritance, inherited members, private vars. in ref. manual
    
    diff --git a/doc/common/builder.py b/doc/common/builder.py
    a b class ReferenceBuilder(DocBuilder): 
    343343        This is the wrapper around the builder_helper methods that
    344344        goes through and makes sure things are up to date.
    345345        """
     346        # Delete the auto-generated .rst files, if the inherited
     347        # members option has changed.
     348        global options
     349        inherit_prev = self.get_cache().get('option_inherited')
     350        if inherit_prev is None or inherit_prev != options.inherited:
     351            logger.info("Detected change in inherited members option.")
     352            self.clean_auto()
     353            self.get_cache.clear_cache()
     354
    346355        # After "sage -clone", refresh the .rst file mtimes in
    347356        # environment.pickle.
    348         if update_mtimes:
     357        if options.update_mtimes:
    349358            logger.info("Checking for .rst file mtimes to update...")
    350359            self.update_mtimes()
    351360
    class ReferenceBuilder(DocBuilder): 
    377386    @cached_method
    378387    def get_cache(self):
    379388        """
    380         Retreive the cache of already generated ReST files.  If it
     389        Retrieve the cache of already generated ReST files.  If it
    381390        doesn't exist, then we just return an empty dictionary.
    382391        """
    383392        filename = self.cache_filename()
    class ReferenceBuilder(DocBuilder): 
    394403        """
    395404        Save the cache of already generated ReST files.
    396405        """
     406        cache = self.get_cache()
     407
     408        global options
     409        cache['option_inherited'] = options.inherited
     410
    397411        import cPickle
    398412        file = open(self.cache_filename(), 'wb')
    399         cPickle.dump(self.get_cache(), file)
     413        cPickle.dump(cache, file)
    400414        file.close()
    401415        logger.debug("Saved .rst file cache: %s", self.cache_filename())
    402416
    class ReferenceBuilder(DocBuilder): 
    599613        outfile.write(title + '\n')
    600614        outfile.write('='*len(title) + "\n\n")
    601615        outfile.write('.. This file has been autogenerated.\n\n')
    602         automodule = '.. automodule:: %s\n   :members:\n   :undoc-members:\n\n'
    603         outfile.write(automodule%module_name)
     616
     617        global options
     618        inherited = ':inherited-members:' if options.inherited else ''
     619
     620        automodule = '''
     621.. automodule:: %s
     622   :members:
     623   :undoc-members:
     624   :show-inheritance:
     625   %s
     626
     627'''
     628        outfile.write(automodule % (module_name, inherited))
    604629
    605630        outfile.close()
    606631
    def setup_parser(): 
    913938                        type="string", metavar="DOC",
    914939                        action="callback", callback=help_wrapper,
    915940                        help="list all COMMANDs for DOCUMENT DOC; use 'all' to list all")
     941
     942    standard.add_option("-i", "--inherited", dest="inherited",
     943                        default=False, action="store_true",
     944                        help="include inherited members in reference manual")
     945    standard.add_option("-u", "--underscore", dest="underscore",
     946                        default=False, action="store_true",
     947                        help="include variables prefixed with '_' in reference manual")
     948
    916949    standard.add_option("-j", "--jsmath", dest="jsmath",
    917950                        action="store_true",
    918951                        help="render math using jsMath; FORMATs: html, json, pickle, web")
    def setup_parser(): 
    937970                        action="store",
    938971                        help="pass comma-separated OPTS to sphinx-build")
    939972    advanced.add_option("-U", "--update-mtimes", dest="update_mtimes",
    940                         action="store_true",
     973                        default=False, action="store_true",
    941974                        help="before building reference manual, update modification times for auto-generated ReST files")
    942975    parser.add_option_group(advanced)
    943976
    if __name__ == '__main__': 
    10181051    if options.jsmath:
    10191052        os.environ['SAGE_DOC_JSMATH'] = "True"
    10201053
     1054    if options.underscore:
     1055        os.environ['SAGE_DOC_UNDERSCORE'] = "True"
     1056
    10211057    if options.sphinx_opts:
    10221058        ALLSPHINXOPTS += options.sphinx_opts.replace(',', ' ') + " "
    10231059
    1024     if options.update_mtimes:
    1025         update_mtimes = True
    1026     else:
    1027         update_mtimes = False
    1028 
    10291060    # Make sure common/static exists.
    10301061    mkdir(os.path.join(SAGE_DOC, 'common', 'static'))
    10311062
  • doc/common/conf.py

    diff --git a/doc/common/conf.py b/doc/common/conf.py
    a b SAGE_DOC = os.path.join(SAGE_ROOT, 'deve 
    1212
    1313# Add any Sphinx extension module names here, as strings. They can be extensions
    1414# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
    15 extensions = ['sphinx.ext.autodoc']
     15extensions = ['sphinx.ext.autodoc',  'sphinx.ext.graphviz',
     16              'sphinx.ext.inheritance_diagram']
     17
     18# GraphViz includes dot, neato, twopi, circo, fdp.
     19graphviz_dot = 'dot'
     20inheritance_graph_attrs = { 'rankdir' : 'BT' }
     21inheritance_node_attrs = { 'height' : 0.5, 'fontsize' : 12, 'shape' : 'oval' }
     22inheritance_edge_attrs = {}
    1623
    1724if 'SAGE_DOC_JSMATH' in os.environ:
    1825    extensions.append('sphinx.ext.jsmath')
    def skip_NestedClass(app, what, name, ob 
    285292    (This is to avoid some Sphinx warnings when processing
    286293    sage.misc.misc.)  Otherwise, abide by Sphinx's decision.
    287294    """
    288     skip_nested = str(obj).find("sage.misc.misc") != -1 and name.find("MainClass.NestedClass") != -1
     295    skip_nested = (str(obj).find("sage.misc.misc") != -1 and
     296                   name.find("MainClass.NestedClass") != -1)
     297
    289298    return skip or skip_nested
    290        
     299
     300def skip_underscore(app, what, name, obj, skip, options):
     301    """
     302    Conditionally include docstrings for objects whose names begin
     303    with an underscore ('_').
     304    """
     305    if 'SAGE_DOC_UNDERSCORE' in os.environ:
     306        if name.split('.')[-1].startswith('_'):
     307            return False
     308
     309    return skip
     310
    291311def process_dollars(app, what, name, obj, options, docstringlines):
    292312    r"""
    293313    Replace dollar signs with backticks.
    def process_dollars(app, what, name, obj 
    345365    for i in range(len(lines)):
    346366        docstringlines[i] = lines[i]
    347367
     368def process_inherited(app, what, name, obj, options, docstringlines):
     369    """
     370    If we're including inherited members, omit their docstrings.
     371    """
     372    if not options.get('inherited-members'):
     373        return
     374
     375    if what in ['class', 'data', 'exception', 'function', 'module']:
     376        return
     377
     378    name = name.split('.')[-1]
     379
     380    if what == 'method' and hasattr(obj, 'im_class'):
     381        if name in obj.im_class.__dict__.keys():
     382            return
     383
     384    if what == 'attribute' and hasattr(obj, '__objclass__'):
     385        if name in obj.__objclass__.__dict__.keys():
     386            return
     387
     388    for i in xrange(len(docstringlines)):
     389        docstringlines.pop()
     390
    348391def setup(app):
    349392    app.connect('autodoc-process-docstring', process_docstring_cython)
    350393    app.connect('autodoc-process-docstring', process_directives)
    351394    app.connect('autodoc-process-docstring', process_docstring_module_title)
    352395    app.connect('autodoc-process-docstring', process_dollars)
     396    app.connect('autodoc-process-docstring', process_inherited)
    353397    app.connect('autodoc-skip-member', skip_NestedClass)
     398    app.connect('autodoc-skip-member', skip_underscore)