Ticket #7549: trac_7549-doc_inheritance_underscore_v4.patch

File trac_7549-doc_inheritance_underscore_v4.patch, 9.4 KB (added by mpatel, 12 years ago)

Rebased vs. 4.3.3.alpha0. See comment. Apply only this patch. sage repo.

  • doc/common/builder.py

    # HG changeset patch
    # User Mitesh Patel <qed777@gmail.com>
    # Date 1259415883 28800
    # Node ID c9ddc4336b4876ff40a8764e5f907872ff8e3449
    # Parent  a8159f6f559990078f2ec3a2799b36005597d9f3
    #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        # and/or underscored members options have changed.
     348        global options
     349        inherit_prev = self.get_cache().get('option_inherited')
     350        underscore_prev = self.get_cache().get('option_underscore')
     351        if (inherit_prev is None or inherit_prev != options.inherited or
     352            underscore_prev is None or underscore_prev != options.underscore):
     353            logger.info("Detected change(s) in inherited and/or underscored members option(s).")
     354            self.clean_auto()
     355            self.get_cache.clear_cache()
     356
    346357        # After "sage -clone", refresh the .rst file mtimes in
    347358        # environment.pickle.
    348         if update_mtimes:
     359        if options.update_mtimes:
    349360            logger.info("Checking for .rst file mtimes to update...")
    350361            self.update_mtimes()
    351362
    class ReferenceBuilder(DocBuilder): 
    377388    @cached_method
    378389    def get_cache(self):
    379390        """
    380         Retreive the cache of already generated ReST files.  If it
     391        Retrieve the cache of already generated ReST files.  If it
    381392        doesn't exist, then we just return an empty dictionary.
    382393        """
    383394        filename = self.cache_filename()
    class ReferenceBuilder(DocBuilder): 
    394405        """
    395406        Save the cache of already generated ReST files.
    396407        """
     408        cache = self.get_cache()
     409
     410        global options
     411        cache['option_inherited'] = options.inherited
     412        cache['option_underscore'] = options.underscore
     413
    397414        import cPickle
    398415        file = open(self.cache_filename(), 'wb')
    399         cPickle.dump(self.get_cache(), file)
     416        cPickle.dump(cache, file)
    400417        file.close()
    401418        logger.debug("Saved .rst file cache: %s", self.cache_filename())
    402419
    class ReferenceBuilder(DocBuilder): 
    599616        outfile.write(title + '\n')
    600617        outfile.write('='*len(title) + "\n\n")
    601618        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)
     619
     620        global options
     621        inherited = ':inherited-members:' if options.inherited else ''
     622
     623        automodule = '''
     624.. automodule:: %s
     625   :members:
     626   :undoc-members:
     627   :show-inheritance:
     628   %s
     629
     630'''
     631        outfile.write(automodule % (module_name, inherited))
    604632
    605633        outfile.close()
    606634
    def setup_parser(): 
    913941                        type="string", metavar="DOC",
    914942                        action="callback", callback=help_wrapper,
    915943                        help="list all COMMANDs for DOCUMENT DOC; use 'all' to list all")
     944
     945    standard.add_option("-i", "--inherited", dest="inherited",
     946                        default=False, action="store_true",
     947                        help="include inherited members in reference manual")
     948    standard.add_option("-u", "--underscore", dest="underscore",
     949                        default=False, action="store_true",
     950                        help="include variables prefixed with '_' in reference manual")
     951
    916952    standard.add_option("-j", "--jsmath", dest="jsmath",
    917953                        action="store_true",
    918954                        help="render math using jsMath; FORMATs: html, json, pickle, web")
    def setup_parser(): 
    940976                        action="store",
    941977                        help="pass comma-separated OPTS to sphinx-build")
    942978    advanced.add_option("-U", "--update-mtimes", dest="update_mtimes",
    943                         action="store_true",
     979                        default=False, action="store_true",
    944980                        help="before building reference manual, update modification times for auto-generated ReST files")
    945981    parser.add_option_group(advanced)
    946982
    if __name__ == '__main__': 
    10211057    if options.jsmath:
    10221058        os.environ['SAGE_DOC_JSMATH'] = "True"
    10231059
     1060    if options.underscore:
     1061        os.environ['SAGE_DOC_UNDERSCORE'] = "True"
     1062
    10241063    if options.sphinx_opts:
    10251064        ALLSPHINXOPTS += options.sphinx_opts.replace(',', ' ') + " "
    10261065    if options.no_pdf_links:
    10271066        ALLSPHINXOPTS += "-A hide_pdf_links=1"
    10281067
    1029     if options.update_mtimes:
    1030         update_mtimes = True
    1031     else:
    1032         update_mtimes = False
    1033 
    10341068    # Make sure common/static exists.
    10351069    mkdir(os.path.join(SAGE_DOC, 'common', 'static'))
    10361070
  • 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#, 'sphinx.ext.intersphinx', 'sphinx.ext.extlinks']
    1618
    1719if 'SAGE_DOC_JSMATH' in os.environ:
    1820    extensions.append('sphinx.ext.jsmath')
    default_role = 'math' 
    8082# This overrides a HTML theme's corresponding setting (see below).
    8183pygments_style = 'sphinx'
    8284
     85# GraphViz includes dot, neato, twopi, circo, fdp.
     86graphviz_dot = 'dot'
     87inheritance_graph_attrs = { 'rankdir' : 'BT' }
     88inheritance_node_attrs = { 'height' : 0.5, 'fontsize' : 12, 'shape' : 'oval' }
     89inheritance_edge_attrs = {}
     90
     91# Sage trac ticket shortcuts. For example, :ticket:`7549` .
     92#extlinks = {'ticket': ('http://trac.sagemath.org/sage_trac/ticket/', 'Ticket ')}
    8393
    8494# Options for HTML output
    8595# -----------------------
    html_split_index = True 
    175185# Output file base name for HTML help builder.
    176186#htmlhelp_basename = ''
    177187
     188# Cross-links to other project's online documentation.
     189#intersphinx_mapping = {'http://docs.python.org/dev': None}
     190
    178191
    179192# Options for LaTeX output
    180193# ------------------------
    def process_docstring_module_title(app,  
    284297        else:
    285298            break
    286299
    287 def skip_NestedClass(app, what, name, obj, skip, options):
     300def skip_member(app, what, name, obj, skip, options):
    288301    """
    289302    Don't include the docstring for any class/function/object in
    290303    sage.misc.misc whose ``name`` contains "MainClass.NestedClass".
    291304    (This is to avoid some Sphinx warnings when processing
    292     sage.misc.misc.)  Otherwise, abide by Sphinx's decision.
     305    sage.misc.misc.)
     306
     307    Conditionally include docstrings for objects whose names begin
     308    with an underscore ('_').
     309
     310    Otherwise, abide by Sphinx's decision.
    293311    """
    294     skip_nested = str(obj).find("sage.misc.misc") != -1 and name.find("MainClass.NestedClass") != -1
    295     return skip or skip_nested
    296        
     312    if (str(obj).find("sage.misc.misc") != -1 and
     313        name.find("MainClass.NestedClass") != -1):
     314        return True
     315
     316    if 'SAGE_DOC_UNDERSCORE' in os.environ:
     317        if name.split('.')[-1].startswith('_'):
     318            return False
     319
     320    return skip
     321
    297322def process_dollars(app, what, name, obj, options, docstringlines):
    298323    r"""
    299324    Replace dollar signs with backticks.
    def process_mathtt(app, what, name, obj, 
    318343        for i in range(len(lines)):
    319344            docstringlines[i] = lines[i]
    320345
     346def process_inherited(app, what, name, obj, options, docstringlines):
     347    """
     348    If we're including inherited members, omit their docstrings.
     349    """
     350    if not options.get('inherited-members'):
     351        return
     352
     353    if what in ['class', 'data', 'exception', 'function', 'module']:
     354        return
     355
     356    name = name.split('.')[-1]
     357
     358    if what == 'method' and hasattr(obj, 'im_class'):
     359        if name in obj.im_class.__dict__.keys():
     360            return
     361
     362    if what == 'attribute' and hasattr(obj, '__objclass__'):
     363        if name in obj.__objclass__.__dict__.keys():
     364            return
     365
     366    for i in xrange(len(docstringlines)):
     367        docstringlines.pop()
     368
    321369from sage.misc.sageinspect import sage_getargspec
    322370autodoc_builtin_argspec = sage_getargspec
    323371
    def setup(app): 
    327375    app.connect('autodoc-process-docstring', process_docstring_module_title)
    328376    app.connect('autodoc-process-docstring', process_dollars)
    329377    app.connect('autodoc-process-docstring', process_mathtt)
    330     app.connect('autodoc-skip-member', skip_NestedClass)
     378    app.connect('autodoc-process-docstring', process_inherited)
     379    app.connect('autodoc-skip-member', skip_member)
  • sage/combinat/lyndon_word.py

    diff --git a/sage/combinat/lyndon_word.py b/sage/combinat/lyndon_word.py
    a b  
     1# -*- coding: utf-8 -*-
    12"""
    23Lyndon words
    34"""
  • sage/interfaces/singular.py

    diff --git a/sage/interfaces/singular.py b/sage/interfaces/singular.py
    a b class SingularFunctionElement(FunctionEl 
    17691769       
    17701770            sage: R = singular.ring(0, '(x,y,z)', 'dp')
    17711771            sage: A = singular.matrix(2,2)
    1772             sage: A.nrows._sage_doc_()
    1773             "\nnrows\n-----\n\n`*Syntax:*'\n ...
    17741772        """
    17751773        if not nodes:
    17761774            generate_docstring_dictionary()