Mailman 3 January 1997 - Doc-SIG

Re: [PYTHON DOC-SIG] Who is hacking?
by Ka-Ping Yee Jan. 30, 1997

Jan. 30, 1997

Just to let you guys know that i haven't disappeared off the face of the earth -- i am interested in the documentation work, and was hoping to be able to spend some time working on it -- it's just that my PC got stolen last November, so i haven't got much of a development machine to work on. :( Anyway, i had a few ideas from before that are buried in my mailbox somewhere. I'll be watching what happens on this list... Ping _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

[PYTHON DOC-SIG] Who is hacking?
by Mark Hammond Jan. 29, 1997

Jan. 29, 1997

What is the current development status of "gendoc" at the moment? I take it Robin and Daniel are the main keepers - does this responsibility divide somewhere? Are there any good test cases (even private ones people use themselves). If I get brave and start trying to enhance, will people actually pick up the patches, and make sure they still work as originally intended :-) My main focusses at the moment are: * Make it generate a hierarchical index for an "ni" package (my previous hacks generates a "flat" index. * Make it parse my already marked-up C++ comments, so I can build a single manual. This should be pretty easy - they are pretty structured, and made more for parsing than reading. * Make my "html2word" tool build good help files from it (it currently does a "reasonable" job!) After doing all that, we'll have a system which can generate a single set of documentation from both .py and .c(pp) sources, and generate it in any of the native gendoc formats, and WinHelp. I reckon that'd be pretty cool :-) Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond(a)skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 2

Re: [PYTHON DOC-SIG] ni and gendoc
by Mark Hammond Jan. 28, 1997

Jan. 28, 1997

> Yes, please do. I haven't had the time I would like to spend on gendoc > recently. > Documenting packages was one of the things I really wanted to do, so I > would > be very happy to get your "hacks". OK - my hacks are below. There is a problem with them, which I can't sort out in a clean way The key change is that instead of unconditionally stripping the extension of a filename, we check if it ".py" or ".pyc", and if not, retain the entire name to be imported. Then a small bit of trickery to get the actual module associated with the full "a.b.c" name (which could be reduced to a 1-liner by going through sy.modules, where it will end up anyway?). I have a problem with HTML generation. In htmlgenformatter.py, there is render_external_link(). This code checks for an extension on the file, and if empty, adds ".html". On "a.b.c", this fails, and no ".html" is appended. My hack here (not included) was to unconditionally add ".html" (ie, just comment out the if) This is not the correct answer, and there are no "reasonable" extensions to check for - the link could be to a custom extenion/format (.pdf/.ps/.anything!). I thought of changing it to generate "a_b_c" from "a.b.c", but this seemed to ingrained to change (ie, object name==filename, but this is not what we want - object name="a.b.c", file name = "a_b_c") Any thoughts on this last little nasty? Mark. *** \temp\doc_collect.py Thu Sep 05 01:35:20 1996 --- doc_collect.py Mon Jan 27 09:56:01 1997 *************** *** 120,132 **** # attribute to determine the module name funcs = filter(lambda member: type(member) == FunctionType, cls.__dict__.values()) if funcs: ! filename = funcs[0].func_code.co_filename ! import os ! module = os.path.splitext(os.path.basename(filename))[0] ! d = {} ! exec 'import %s' % module in d ! _classmap[cls] = d[module] ! return d[module] # import sys clsname = cls.__name__ --- 120,141 ---- # attribute to determine the module name funcs = filter(lambda member: type(member) == FunctionType, cls.__dict__.values()) if funcs: ! try: ! # May be ni ! # Cheat, and assume that the globals for the special ! # attribute '__' is the module. ! mod = funcs[0].func_globals['__'] ! _classmap[cls] = mod ! return mod ! except: ! # Old style. ! filename = funcs[0].func_code.co_filename ! import os ! module = os.path.splitext(os.path.basename(filename))[0] ! d = {} ! exec 'import %s' % module in d ! _classmap[cls] = d[module] ! return d[module] # import sys clsname = cls.__name__ *** \temp\gendoc.py Fri Sep 06 21:06:28 1996 --- gendoc.py Mon Jan 27 14:22:26 1997 *************** *** 239,249 **** modules=[] for file in files: ! dir = os.path.dirname(file) ! if dir and dir not in sys.path: ! sys.path.insert(0, dir) ! ! module = splitfields(os.path.basename(file), '.')[0] dict = {} # Skip certain modules that I know causes problems --- 239,260 ---- modules=[] for file in files: ! base, ext = os.path.splitext(os.path.basename(file)) ! # If the file has a recognised extension, then assume it ! # is a path to a .py file. If no extension, assume it is ! # just a module name which can be directly imported. ! # Note this also supports ni names - eg, the module can contain "." ! if string.lower(ext) in [".py",".pyc"]: ! module = base ! # ensure on path ! dir = os.path.dirname(file) ! if dir and dir not in sys.path: ! sys.path.insert(0, dir) ! ! else: ! # a ni module - assume already on path. ! import ni ! module = file dict = {} # Skip certain modules that I know causes problems *************** *** 257,263 **** try: exec 'import '+module in dict ! modules.append(dict[module]) except SyntaxError: sys.stderr.write('*** Syntax errors in ' + file + '\n'); except: --- 268,281 ---- try: exec 'import '+module in dict ! # We now have done the import, but must walk down the ! # "." sep'd sub-attributes in the module name ! portions = splitfields(module,".") ! look = dict[portions[0]] ! for subAttr in portions[1:]: ! look = getattr(look, subAttr) ! ! modules.append(look) except SyntaxError: sys.stderr.write('*** Syntax errors in ' + file + '\n'); except: ---------------------------------------------------------------------- Mark Hammond - MHammond(a)skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

[PYTHON DOC-SIG] Links to other internal functions/classes?
by Mark Hammond Jan. 28, 1997

Jan. 28, 1997

Hi, Id like to include a link to another function in my documentation. Eg, "See also <{module}.other_func>" where we have a link to the generated documentation for that function/class/etc. Ive had a look, and tried a few things. Couldnt make anything work... What is ~ for? It comes out as literal for me - in _everything_ - including the doc generated from gendoc.py! Ive only tried HTMLg, which may be a problem) Also, I had a quick play with "HTML", (as opposed to HTMLg) and it was missing render_deflist() (??). It has probably already been added, but give me a yell if you want my version :-) Oh yeah - one last thing - both import and parser mode do work on Win32 (except most people will not have parser in binary, but a .pyd exists) - so you can add this OS to the list supported :-) Thanks, Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond(a)skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

Re: [PYTHON DOC-SIG] Links to other internal functions/classes?
by friedric＠rose.rsoc.rockwell.com Jan. 27, 1997

Jan. 27, 1997

|> From: "Mark Hammond" <MHammond(a)skippinet.com.au> |> |> Hi, |> |> Id like to include a link to another function in my documentation. |> Eg, "See also <{module}.other_func>" where we have a link to the generated |> documentation for that function/class/etc. |> |> Ive had a look, and tried a few things. Couldnt make anything |> work... Sorry no help here. Daniel will have to look at this as a new requirement. |> |> What is ~ for? It comes out as literal for me - in _everything_ - |> including the doc generated from gendoc.py! Ive only tried HTMLg, |> which may be a problem) Tilde (~) isn't supposed to be special w.r.t. gendoc. Are you saying the it's acting special in some way? It used to mean Italic but this was changed and now *italic* is used for that. |> |> Also, I had a quick play with "HTML", (as opposed to HTMLg) and it |> was missing render_deflist() (??). It has probably already been |> added, but give me a yell if you want my version :-) Known bug. Forward the version of the fix anyway. |> |> Oh yeah - one last thing - both import and parser mode do work on |> Win32 (except most people will not have parser in binary, but a .pyd |> exists) - so you can add this OS to the list supported :-) Cool. -Robin _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

Re: [PYTHON DOC-SIG] gendoc, etc.
by friedric＠rose.rsoc.rockwell.com Jan. 24, 1997

Jan. 24, 1997

|> From: "Mark Hammond" <MHammond(a)skippinet.com.au> |> Date: Fri, 24 Jan 1997 15:28:26 +1000 |> |> > Thanks. This is shaping up. |> |> Yeah - FWIW, it looks _very_ good. Im very impressed with the |> possibilities. |> |> I may even write a parser that can take my already marked-up C++ |> sources, and generate docs from there too (I have a tool which makes |> RTF). Then an RTF formatter, and we will have winhelp files :-) |> |> But Im getting ahead of my self. |> |> One small problem Im having - Functions _sometimes_ dont get |> docstrings. |> |> Eg: |> def foo(): # No underscores - saw that bit :-) |> "This is foo" |> the_code... yes, the bug you're running into is that for some reason a doc string in a top level function must have a newline in it to be detected as having a doc string. Note that this doesn't seem to affect methods or classes. The following would work however... def foo(): """This is foo. """ the_code... |> |> I get foo listed as a function in the module, but no docstring for |> it.... |> |> Thanks, |> |> Mark. _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

Re: [PYTHON DOC-SIG] gendoc, etc.
by friedric＠rose.rsoc.rockwell.com Jan. 24, 1997

Jan. 24, 1997

Example 'code' is signified by single quotes. The StructuredText.py module documents the rules. I'll try to come up with a good gendoc test module. _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

[PYTHON DOC-SIG] ni and gendoc
by Mark Hammond Jan. 24, 1997

Jan. 24, 1997

Howdy all, Ive just started using gendoc. After a bit of head-bashing, I got it working pretty well. Unfortunately, I am trying to document a package. Ive made a few hacks to make this work in "-i" mode, but Im not sure they are correct. Should I send them? Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond(a)skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1

Re: [PYTHON DOC-SIG] gendoc, etc.
by Mark Hammond Jan. 24, 1997

Jan. 24, 1997

> Thanks. This is shaping up. Yeah - FWIW, it looks _very_ good. Im very impressed with the possibilities. I may even write a parser that can take my already marked-up C++ sources, and generate docs from there too (I have a tool which makes RTF). Then an RTF formatter, and we will have winhelp files :-) But Im getting ahead of my self. One small problem Im having - Functions _sometimes_ dont get docstrings. Eg: def foo(): # No underscores - saw that bit :-) "This is foo" the_code... I get foo listed as a function in the module, but no docstring for it.... Thanks, Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond(a)skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

Re: [PYTHON DOC-SIG] gendoc, etc.
by friedric＠rose.rsoc.rockwell.com Jan. 23, 1997

Jan. 23, 1997

Well I guess I'm one of the few who use gendoc without problems :-\ Some pointers: I use gendoc as follows: gendoc -i -d html -f HTMLg -h HTMLgen HTMLgen.py HTMLcolors.py HTMLutil.py Notice I use the -i option. This tells gendoc to import the modules in order to get the doc strings. If you don't do this, I think the default is the parse option (which requires Fred Drake's Python parser module to be built at your site). Importing is far faster and less problematic so I recommend use of the -i option. The HTMLg formatter (which makes calls to HTMLgen, so it'll have to be in your pythonpath) seems to work fine. If you have several modules and would like to have HTML generated with frames for quick navigation, be sure to set the environment variable FRAME to something non null. As far as your render_deflist problem I have it too when using the plain HTML formatter so I suspect there is something wrong with it. gendoc -f HTML gendoc_test.py will have several problems. For one, and this is a trick, you can't run gendoc while your current directory is the gendoc directory itself. So to run the above test I moved the gendoc_test.py file to another directory and did the following based on the above recommendations: gendoc -i -f HTMLg gendoc_test.py and it worked. You might want to compare your gendoc directory list with mine below to see if there are any missing files. Good luck! Robin drwxr-xr-x 3 friedric admin 1024 Jan 13 13:50 ./ drwxr-xr-x 46 friedric admin 6144 Jan 13 13:50 ../ -r--r--r-- 1 friedric admin 950 Jul 12 1996 ABBLICENSE.DOC -r--r--r-- 1 friedric admin 832 Jul 12 1996 ANNOUNCE.docco -r--r--r-- 1 friedric admin 7890 Jul 12 1996 ASTWalker.py -r--r--r-- 1 friedric admin 5772 Jul 12 1996 HTMLindex.py -rw-r--r-- 1 friedric admin 4589 Sep 17 16:28 HTMLindex.pyc -r--r--r-- 1 friedric admin 950 Jul 12 1996 LICENSE.DOC -r--r--r-- 1 friedric admin 2647 Sep 6 04:57 Makefile -r--r--r-- 1 friedric admin 16805 Sep 6 16:41 ManualPage.py -rw-r--r-- 1 friedric admin 16114 Sep 17 16:28 ManualPage.pyc -r--r--r-- 1 friedric admin 12561 Sep 6 04:58 ParseCollect.py -r--r--r-- 1 friedric admin 4563 Sep 6 05:28 README -r--r--r-- 1 friedric admin 1643 Jul 12 1996 README.docco -r--r--r-- 1 friedric admin 9229 Aug 26 15:31 StructuredText.py -rw-r--r-- 1 friedric admin 10201 Sep 17 16:28 StructuredText.pyc -r--r--r-- 1 friedric admin 497 Jul 12 1996 TODO -r--r--r-- 1 friedric admin 61 Jul 12 1996 __init__.py -rw-r--r-- 1 friedric admin 201 Sep 17 16:28 __init__.pyc -r--r--r-- 1 friedric admin 7698 Jul 12 1996 ast.py -r--r--r-- 1 friedric admin 6835 Jul 12 1996 ast_doc.py -r--r--r-- 1 friedric admin 20188 Sep 4 09:35 doc_collect.py -rw-r--r-- 1 friedric admin 24575 Sep 17 16:28 doc_collect.pyc -r--r--r-- 1 friedric admin 3231 Sep 18 07:50 docregex.py -rw-r--r-- 1 friedric admin 1497 Oct 2 16:19 docregex.pyc -r--r--r-- 1 friedric admin 8573 Sep 6 14:14 docutil.py -rw-r--r-- 1 friedric admin 8488 Sep 17 16:28 docutil.pyc drwxr-xr-x 2 friedric admin 512 Jan 13 13:50 formatters/ -r-xr-xr-x 1 friedric admin 82 Sep 3 14:44 gendoc* -r--r--r-- 1 friedric admin 11349 Sep 6 05:06 gendoc.py -rw-r--r-- 1 friedric admin 10739 Sep 17 16:28 gendoc.pyc -r--r--r-- 1 friedric admin 2847 Sep 6 14:19 gendoc_test.py -rw-r--r-- 1 friedric admin 9347 Sep 11 11:08 index.htp -r--r--r-- 1 friedric admin 165 Jul 12 1996 symbol.py -r--r--r-- 1 friedric admin 1050 Jul 12 1996 symbol_v1_3.py -r--r--r-- 1 friedric admin 1062 Jul 12 1996 symbol_v1_4.py -r--r--r-- 1 friedric admin 162 Jul 12 1996 token.py -r--r--r-- 1 friedric admin 849 Jul 12 1996 token_v1_3.py -r--r--r-- 1 friedric admin 864 Jul 12 1996 token_v1_4.py ./formatters: total 166 drwxr-xr-x 2 friedric admin 512 Jan 13 13:50 ./ drwxr-xr-x 3 friedric admin 1024 Jan 13 13:50 ../ -r--r--r-- 1 friedric admin 3785 Sep 6 05:09 ASCIIFormatter.py -rw-r--r-- 1 friedric admin 4204 Sep 17 16:28 ASCIIFormatter.pyc -r--r--r-- 1 friedric admin 5000 Sep 6 05:12 Formatters.py -rw-r--r-- 1 friedric admin 4183 Sep 17 16:28 Formatters.pyc -r--r--r-- 1 friedric admin 914 Jul 9 1996 HTML.rc -r--r--r-- 1 friedric admin 4373 Jul 8 1996 HTMLFormatter.py -rw-r--r-- 1 friedric admin 6231 Sep 17 16:28 HTMLFormatter.pyc -r--r--r-- 1 friedric admin 6999 Sep 17 16:48 HTMLgenFormatter.py -rw-r--r-- 1 friedric admin 8971 Sep 17 17:02 HTMLgenFormatter.pyc -r--r--r-- 1 friedric admin 7164 Sep 6 05:10 MIFFormatter.py -rw-r--r-- 1 friedric admin 8137 Sep 17 16:28 MIFFormatter.pyc -r--r--r-- 1 friedric admin 6701 Sep 6 05:11 MMLFormatter.py -rw-r--r-- 1 friedric admin 7311 Sep 17 16:28 MMLFormatter.pyc -r--r--r-- 1 friedric admin 144 Jul 8 1996 __init__.py -rw-r--r-- 1 friedric admin 267 Sep 17 16:28 __init__.pyc -r--r--r-- 1 friedric admin 362 Jun 24 1996 tags.mml _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1