Commits

Mike Bayer committed 6511dd2

- fixed textual select elements that got broke the other day
- docstring work

Comments (0)

Files changed (6)

doc/build/genhtml.py

 from mako.lookup import TemplateLookup
 from mako import exceptions, runtime
 import time
+import optparse
 
 files = [
     'index',
-    'documentation',
+#    'documentation',
     'tutorial',
     'dbengine',
     'metadata',
     'docstrings'
     ]
 
-argfile = len(sys.argv) > 1 and sys.argv[1]
-if argfile:
-    files = [argfile]
-    
+parser = optparse.OptionParser(usage = "usage: %prog [options] [tests...]")
+parser.add_option("--file", action="store", dest="file", help="only generate file <file>")
+parser.add_option("--docstrings", action="store_true", dest="docstrings", help="only generate docstrings")
+
+(options, args) = parser.parse_args()
+if options.file:
+    files = [file]
+
 title='SQLAlchemy 0.3 Documentation'
 version = '0.3.6'
 
 shutil.copy('./content/docstrings.html', './output/docstrings.html')
 shutil.copy('./content/documentation.html', './output/documentation.html')
 
-read_markdown.parse_markdown_files(root, files)
+if not options.docstrings:
+    read_markdown.parse_markdown_files(root, files)
 
-if not argfile:
+if not options.file or options.docstrings:
     docstrings = gen_docstrings.make_all_docs()
     doc_files = gen_docstrings.create_docstring_toc(docstrings, root)
 
     t = lookup.get_template(infile)
     outfile.write(t.render(attributes={}))
 
-for filename in files:
-    try:
-        genfile(filename, os.path.join(os.getcwd(), '../', filename + ".html"))
-    except:
-        print exceptions.text_error_template().render()
+if not options.docstrings:
+    for filename in files:
+        try:
+            genfile(filename, os.path.join(os.getcwd(), '../', filename + ".html"))
+        except:
+            print exceptions.text_error_template().render()
 
-if not argfile:
+if not options.file or options.docstrings:
     for filename in doc_files:
         try:
             genfile(filename, os.path.join(os.getcwd(), '../', os.path.basename(filename) + ".html"))

doc/build/lib/docstring.py

                     and 
                     (getattr(obj, x).__name__ == '__init__' or not getattr(obj,x).__name__[0] == '_')
                     ] + 
-                    [(x, getattr(obj, x)) for x in obj.__dict__.keys() if isinstance(getattr(obj,x), property) 
+                    [(x, getattr(obj, x)) for x in obj.__dict__.keys() if _is_property(getattr(obj,x)) 
                     and 
                     not x[0] == '_'
                     ]
     def accept_visitor(self, visitor):
         visitor.visit_object(self)
 
+def _is_property(elem):
+    return isinstance(elem, property) or (hasattr(elem, '__get__') and hasattr(elem, '__set__'))
+    
 class FunctionDoc(AbstractDoc):
     def __init__(self, func):
         super(FunctionDoc, self).__init__(func)

doc/build/templates/pydoc.html

                 % if isinstance(func, docstring.FunctionDoc):
                     ${function_doc(func=func, toc=toc, extension=extension, paged=paged)}
                 % elif isinstance(func, docstring.PropertyDoc):
-                    ${property_doc(prop=func)}
+                    ${property_doc(prop=func, toc=toc, extension=extension, paged=paged)}
                 % endif
             % endfor
         % endif
     </div>
 </%def>
 
-<%def name="property_doc(prop)">
+<%def name="property_doc(prop, toc, extension, paged)">
          <div class="darkcell">
          <A name=""></a>
          <b>${prop.name} = property()</b>
          <div class="docstring">
-         ${prop.doc or '' | formatdocstring}
+         ${prop.doc or '' | formatdocstring, inline_links(toc, extension, paged)}
          </div> 
          </div>
 </%def>

lib/sqlalchemy/engine/base.py

     def execute(self, object, *multiparams, **params):
         raise NotImplementedError()
 
-    def _not_impl(self):
-        raise NotImplementedError()
-
-    engine = property(_not_impl, doc="The Engine which this Connectable is associated with.")
-    dialect = property(_not_impl, doc="Dialect which this Connectable is associated with.")
+    engine = util.NotImplProperty("The Engine which this Connectable is associated with.")
+    dialect = util.NotImplProperty("Dialect which this Connectable is associated with.")
 
 class Connection(Connectable):
     """Represent a single DBAPI connection returned from the underlying connection pool.

lib/sqlalchemy/sql.py

         return obj.type
 
 class Selectable(ClauseElement):
-    """Represent a column list-holding object."""
+    """Represent a column list-holding object.
+    
+    this is the common base class of [sqlalchemy.sql#ColumnElement]
+    and [sqlalchemy.sql#FromClause].  The reason ``ColumnElement``
+    is marked as a "list-holding" object is so that it can be treated
+    similarly to ``FromClause`` in column-selection scenarios; it 
+    contains a list of columns consisting of itself.
+    
+    """
+
+    columns = util.NotImplProperty("""a [sqlalchemy.sql#ColumnCollection] containing ``ColumnElement`` instances.""")
 
     def _selectable(self):
         return self
 
     def append_column(self, column):
         if _is_literal(column):
-            column = literal_column(str(column), table=self)
+            column = literal_column(str(column))
 
         self._raw_columns.append(column)
 

lib/sqlalchemy/util.py

         else:
             return getattr(obj, self.key)
 
+class NotImplProperty(object):
+  """a property that raises ``NotImplementedError``."""
+  
+  def __init__(self, doc):
+      self.__doc__ = doc
+      
+  def __set__(self, obj, value):
+      raise NotImplementedError()
+
+  def __delete__(self, obj):
+      raise NotImplementedError()
+
+  def __get__(self, obj, owner):
+      if obj is None:
+          return self
+      else:
+          raise NotImplementedError()
+  
 class OrderedProperties(object):
     """An object that maintains the order in which attributes are set upon it.