Ticket #7549: trac_7549-doc_inheritance_underscore_v5.patch

File trac_7549-doc_inheritance_underscore_v5.patch, 9.0 KB (added by mpatel, 12 years ago)

Rebase vs. 4.3.4.alpha1 + #8457. Apply only this patch.

  • doc/common/builder.py

    # HG changeset patch
    # User Mitesh Patel <qed777@gmail.com>
    # Date 1259415883 28800
    # Node ID a6ba26f7c08c2c364e1431418c96ea5ef8f3b337
    # Parent  9b7119d4882dd910ec7dd31ede259688251d8f60
    #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(): 
    942978                        action="store",
    943979                        help="pass comma-separated OPTS to sphinx-build")
    944980    advanced.add_option("-U", "--update-mtimes", dest="update_mtimes",
    945                         action="store_true",
     981                        default=False, action="store_true",
    946982                        help="before building reference manual, update modification times for auto-generated ReST files")
    947983    parser.add_option_group(advanced)
    948984
    if __name__ == '__main__': 
    10261062    if options.check_nested:
    10271063        os.environ['SAGE_CHECK_NESTED'] = 'True'
    10281064
     1065    if options.underscore:
     1066        os.environ['SAGE_DOC_UNDERSCORE'] = "True"
     1067
    10291068    if options.sphinx_opts:
    10301069        ALLSPHINXOPTS += options.sphinx_opts.replace(',', ' ') + " "
    10311070    if options.no_pdf_links:
    10321071        ALLSPHINXOPTS += "-A hide_pdf_links=1"
    10331072
    1034     if options.update_mtimes:
    1035         update_mtimes = True
    1036     else:
    1037         update_mtimes = False
    1038 
    10391073    # Make sure common/static exists.
    10401074    mkdir(os.path.join(SAGE_DOC, 'common', 'static'))
    10411075
  • doc/common/conf.py

    diff --git a/doc/common/conf.py b/doc/common/conf.py
    a b sys.path.append(os.path.abspath(os.path. 
    1313
    1414# Add any Sphinx extension module names here, as strings. They can be extensions
    1515# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
    16 extensions = ['sage_autodoc']
     16extensions = ['sage_autodoc',  'sphinx.ext.graphviz',
     17              'sphinx.ext.inheritance_diagram']
     18#, 'sphinx.ext.intersphinx', 'sphinx.ext.extlinks']
    1719
    1820if 'SAGE_DOC_JSMATH' in os.environ:
    1921    extensions.append('sphinx.ext.jsmath')
    default_role = 'math' 
    8183# This overrides a HTML theme's corresponding setting (see below).
    8284pygments_style = 'sphinx'
    8385
     86# GraphViz includes dot, neato, twopi, circo, fdp.
     87graphviz_dot = 'dot'
     88inheritance_graph_attrs = { 'rankdir' : 'BT' }
     89inheritance_node_attrs = { 'height' : 0.5, 'fontsize' : 12, 'shape' : 'oval' }
     90inheritance_edge_attrs = {}
     91
     92# Sage trac ticket shortcuts. For example, :ticket:`7549` .
     93#extlinks = {'ticket': ('http://trac.sagemath.org/sage_trac/ticket/', 'Ticket ')}
    8494
    8595# Options for HTML output
    8696# -----------------------
    html_split_index = True 
    176186# Output file base name for HTML help builder.
    177187#htmlhelp_basename = ''
    178188
     189# Cross-links to other project's online documentation.
     190#intersphinx_mapping = {'http://docs.python.org/dev': None}
     191
    179192
    180193# Options for LaTeX output
    181194# ------------------------
    def skip_member(app, what, name, obj, sk 
    329342
    330343    - Optionally, check whether pickling is broken for nested classes.
    331344
     345    - Optionally, include objects whose name begins with an underscore
     346      ('_'), i.e., "private" or "hidden" attributes, methods, etc.
     347
    332348    Otherwise, we abide by Sphinx's decision.  Note: The object
    333349    ``obj`` is excluded (included) if this handler returns True
    334350    (False).
    def skip_member(app, what, name, obj, sk 
    346362    if name.find("userchild_download_worksheets.zip") != -1:
    347363        return True
    348364
     365    if 'SAGE_DOC_UNDERSCORE' in os.environ:
     366        if name.split('.')[-1].startswith('_'):
     367            return False
     368
    349369    return skip
    350370
    351371def process_dollars(app, what, name, obj, options, docstringlines):
    def process_mathtt(app, what, name, obj, 
    373393        for i in range(len(lines)):
    374394            docstringlines[i] = lines[i]
    375395
     396def process_inherited(app, what, name, obj, options, docstringlines):
     397    """
     398    If we're including inherited members, omit their docstrings.
     399    """
     400    if not options.get('inherited-members'):
     401        return
     402
     403    if what in ['class', 'data', 'exception', 'function', 'module']:
     404        return
     405
     406    name = name.split('.')[-1]
     407
     408    if what == 'method' and hasattr(obj, 'im_class'):
     409        if name in obj.im_class.__dict__.keys():
     410            return
     411
     412    if what == 'attribute' and hasattr(obj, '__objclass__'):
     413        if name in obj.__objclass__.__dict__.keys():
     414            return
     415
     416    for i in xrange(len(docstringlines)):
     417        docstringlines.pop()
     418
    376419from sage.misc.sageinspect import sage_getargspec
    377420autodoc_builtin_argspec = sage_getargspec
    378421
    def setup(app): 
    382425    app.connect('autodoc-process-docstring', process_docstring_module_title)
    383426    app.connect('autodoc-process-docstring', process_dollars)
    384427    app.connect('autodoc-process-docstring', process_mathtt)
     428    app.connect('autodoc-process-docstring', process_inherited)
    385429    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()