Ticket #7549: trac_7549-doc_inheritance_underscore_v3.patch

File trac_7549-doc_inheritance_underscore_v3.patch, 8.9 KB (added by mpatel, 12 years ago)

Rebased for 4.3.alpha1. Replaces previous patches.

  • doc/common/builder.py

    # HG changeset patch
    # User Mitesh Patel <qed777@gmail.com>
    # Date 1259415883 28800
    # Node ID c066caa85a9cf4d7cecb20d7a029786fe3c82345
    # Parent  ebb021b50ecb05bcf7f7f3dd21c47232b3347de5
    #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(): 
    940973                        action="store",
    941974                        help="pass comma-separated OPTS to sphinx-build")
    942975    advanced.add_option("-U", "--update-mtimes", dest="update_mtimes",
    943                         action="store_true",
     976                        default=False, action="store_true",
    944977                        help="before building reference manual, update modification times for auto-generated ReST files")
    945978    parser.add_option_group(advanced)
    946979
    if __name__ == '__main__': 
    10211054    if options.jsmath:
    10221055        os.environ['SAGE_DOC_JSMATH'] = "True"
    10231056
     1057    if options.underscore:
     1058        os.environ['SAGE_DOC_UNDERSCORE'] = "True"
     1059
    10241060    if options.sphinx_opts:
    10251061        ALLSPHINXOPTS += options.sphinx_opts.replace(',', ' ') + " "
    10261062    if options.no_pdf_links:
    10271063        ALLSPHINXOPTS += "-A hide_pdf_links=1"
    10281064
    1029     if options.update_mtimes:
    1030         update_mtimes = True
    1031     else:
    1032         update_mtimes = False
    1033 
    10341065    # Make sure common/static exists.
    10351066    mkdir(os.path.join(SAGE_DOC, 'common', 'static'))
    10361067
  • 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', 'sphinx.ext.intersphinx']
     17#              '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 
    173183# Output file base name for HTML help builder.
    174184#htmlhelp_basename = ''
    175185
     186# Cross-links to other project's online documentation.
     187intersphinx_mapping = {'http://docs.python.org/dev': None}
     188
    176189
    177190# Options for LaTeX output
    178191# ------------------------
    def skip_NestedClass(app, what, name, ob 
    285298    (This is to avoid some Sphinx warnings when processing
    286299    sage.misc.misc.)  Otherwise, abide by Sphinx's decision.
    287300    """
    288     skip_nested = str(obj).find("sage.misc.misc") != -1 and name.find("MainClass.NestedClass") != -1
     301    skip_nested = (str(obj).find("sage.misc.misc") != -1 and
     302                   name.find("MainClass.NestedClass") != -1)
     303
    289304    return skip or skip_nested
    290        
     305
     306def skip_underscore(app, what, name, obj, skip, options):
     307    """
     308    Conditionally include docstrings for objects whose names begin
     309    with an underscore ('_').
     310    """
     311    if 'SAGE_DOC_UNDERSCORE' in os.environ:
     312        if name.split('.')[-1].startswith('_'):
     313            return False
     314
     315    return skip
     316
    291317def process_dollars(app, what, name, obj, options, docstringlines):
    292318    r"""
    293319    Replace dollar signs with backticks.
    def process_dollars(app, what, name, obj 
    345371    for i in range(len(lines)):
    346372        docstringlines[i] = lines[i]
    347373
     374def process_inherited(app, what, name, obj, options, docstringlines):
     375    """
     376    If we're including inherited members, omit their docstrings.
     377    """
     378    if not options.get('inherited-members'):
     379        return
     380
     381    if what in ['class', 'data', 'exception', 'function', 'module']:
     382        return
     383
     384    name = name.split('.')[-1]
     385
     386    if what == 'method' and hasattr(obj, 'im_class'):
     387        if name in obj.im_class.__dict__.keys():
     388            return
     389
     390    if what == 'attribute' and hasattr(obj, '__objclass__'):
     391        if name in obj.__objclass__.__dict__.keys():
     392            return
     393
     394    for i in xrange(len(docstringlines)):
     395        docstringlines.pop()
     396
    348397def setup(app):
    349398    app.connect('autodoc-process-docstring', process_docstring_cython)
    350399    app.connect('autodoc-process-docstring', process_directives)
    351400    app.connect('autodoc-process-docstring', process_docstring_module_title)
    352401    app.connect('autodoc-process-docstring', process_dollars)
     402    app.connect('autodoc-process-docstring', process_inherited)
    353403    app.connect('autodoc-skip-member', skip_NestedClass)
     404    app.connect('autodoc-skip-member', skip_underscore)
  • 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 
    17481748       
    17491749            sage: R = singular.ring(0, '(x,y,z)', 'dp')
    17501750            sage: A = singular.matrix(2,2)
    1751             sage: A.nrows._sage_doc_()
    1752             "\nnrows\n-----\n\n`*Syntax:*'\n ...
    17531751        """
    17541752        if not nodes:
    17551753            generate_docstring_dictionary()