[py-svn] r35379 - py/dist/py/documentation

[fijal at codespeak.net]

Author: fijal
Date: Wed Dec  6 12:45:52 2006
New Revision: 35379

Modified:
   py/dist/py/documentation/source-viewer.txt
Log:
Make more human-readable format


Modified: py/dist/py/documentation/source-viewer.txt
==============================================================================
--- py/dist/py/documentation/source-viewer.txt	(original)
+++ py/dist/py/documentation/source-viewer.txt	Wed Dec  6 12:45:52 2006
@@ -2,44 +2,43 @@
 Source viewer for pylib
 =======================
 
-Random notes:
--------------
+Purpose:
+--------
 
-* We want to construct this using an AST. Introspection is somehow better in
-  many many places, but an AST is more sticked to source (which is by
-  conincidence what we actually want to see). Additional stuff like things
-  attached to the module might be nice if we want to document them, but
-  they do not appear in source.
-
-* We want to have rather free (without all AST hassle) access to basic
-  info about classess, functions variables etc. So we can get all the
-  necessary informations even if the module has changed a bit.
-
-* We want this access for both SVN and file based sources.
-
-* We want to have html backend of those - which means at least syntax
-  highlightning with possibility of linking to those items.
-
-* Some crosslinking might be cool, variables are resolved syntactically,
-  so in 95% cases we can crossling to at least module.function, module.class
-  etc.
-
-* First: We don't want to have *ANY* type inference there. Two: If at
-  any point we want such thing, we make it through introspection, but better
-  not at all.
-
-Implementation notes:
----------------------
-
-Let's use compiler package and if at any point there will be sth better,
-like pypy's compiler package we'll move. We create out of AST stuff which
-can be accessed by dot. Like module.function.firstlineno, with interface
-to py.code.Source as well.
-
-We can use introspection for some aspects. Right now only top-level functions
-and classes (not laying inside if and such) are exposed. We can use
-introspection to check which functions are exposed at a module level
-(all the ifs and such are executed ususally during initialisation of
-module, so we'll have all of necessary informations). Also we can check
-if elements was not overwritten, or has changed name by compiling code
-and checking.
+As usual, main driving force to develop sth new is lack of several
+possibilities between existing solutions. Major lack of features are:
+
+* Impossible to link to certain function like http://filename#function_name
+
+* Impossible to properly link - most informations coming from AST
+
+* We want this to nicely integrate with apigen - so crosslinking from
+  one to another makes sense (also backwards - like info for a function)
+
+Idea:
+-----
+
+Basic idea is to take module as a py.path object, compile it (using compiler
+module), than try to get some information and eventually import it and
+get even some more information. Importing is optional and can be not performed
+at all, but::
+
+ if 1:
+    def f(x):
+       pass
+ if 0:
+    def g(x):
+       pass
+
+could be only parsed well in case of importing stuff. There are also plans for
+integrating more features ie. caching it by code and attaching a name to a code
+generated by some magic functions.
+
+Status:
+-------
+
+Right now there is ready `server`_ and along with an `API viewer`_. Next step
+is to improve a look & feel of API viewer and to link one to another.
+
+.. _`server`: http://johnnydebris.net:8000/py/test/collect.py#Collector
+.. _`API viewer`: http://johnnydebris.net/xxx