Ticket #7549: trac_7549-doc_inheritance_underscore_v2.patch

File trac_7549-doc_inheritance_underscore_v2.patch, 8.8 KB (added by mpatel, 12 years ago)

Set up intersphinx for Python docs. Replaces previous patch. sage repo.

  • doc/common/builder.py

    # HG changeset patch
    # User Mitesh Patel <qed777@gmail.com>
    # Date 1259415883 28800
    # Node ID 0e80e620fcc15f5df0d49b62dc90883732c342cd
    # 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', '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        try:
    17551753            return nodes[node_names[self._name]]