From da@maigret.cog.brown.edu Thu Jan 23 19:42:25 1997 From: da@maigret.cog.brown.edu (David Ascher) Date: Thu, 23 Jan 1997 14:42:25 -0500 (EST) Subject: [PYTHON DOC-SIG] gendoc, etc. Message-ID: <199701231942.OAA08028@maigret> Hi folks. I recently posted on the main list asking for a tool to document existing code, and Daniel Larsson reminded me of gendoc, which I hadn't played with in ages. I got the version which is available from the SIG page, and I'm having consistent problems with it. Are folks using it, or is there a version somewhere else which is more stable? I'm having problems which range from some strange behavior in parsing structured text, to the fact that it crashes when parsing what I think is a pretty simple .py file, and only does a partial job of the doc generation. Also, for whatever reason it's not detecting the HTMLgen formatter even though it's in the formatters directory. Running gendoc -f HTML gendoc_test.py results in: Traceback (innermost last): File "/usr/local/bin/gendoc", line 5, in ? gendoc.gendoc.main() File "gendoc/gendoc.py", line 229, in main File "gendoc/gendoc.py", line 316, in render_manpages File "gendoc/gendoc.py", line 337, in render_pages File "gendoc/gendoc.py", line 365, in render_page File "gendoc/ManualPage.py", line 322, in render File "gendoc/ManualPage.py", line 393, in _render_subsection File "gendoc/ManualPage.py", line 393, in _render_subsection File "gendoc/ManualPage.py", line 450, in _render_deflist AttributeError: render_deflist I can go dig in the code to figure these things out, but I thought I'd ask first if there were tricks (or other releases) that I should know about. Cheers, David_Ascher@Brown.EDU (401) 863-3926 # Python is my favorite language: http://www.python.org # _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From friedric@rose.rsoc.rockwell.com Thu Jan 23 20:41:33 1997 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Thu, 23 Jan 1997 14:41:33 -0600 Subject: [PYTHON DOC-SIG] gendoc, etc. Message-ID: <199701232041.OAA07999@darwin.rsoc.rockwell.com> 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@python.org administrivia to: doc-sig-request@python.org _______________ From da@maigret.cog.brown.edu Thu Jan 23 21:15:08 1997 From: da@maigret.cog.brown.edu (David Ascher) Date: Thu, 23 Jan 1997 16:15:08 -0500 (EST) Subject: [PYTHON DOC-SIG] gendoc, etc. In-Reply-To: <199701232041.OAA07999@darwin.rsoc.rockwell.com> from "Robin Friedrich" at Jan 23, 97 02:41:33 pm Message-ID: <199701232115.QAA08790@maigret> Thanks for the pointers. I'd recommend that gendoc complain if one uses the -d option without the appropriate directory existing (or create it automatically). Right now it dies with an uninformative error message. [should I submit patches instead of bugreports?] Thanks. It now works at least mostly. =) What's the right markup for including sample code in a docstring? I tried just adding the word example on the line before, but that doesn't always work. E.g., in code like the following EXAMPLE: def foo(): do something do something else it reverts out of example mode after the blank line (but only within a def?). Also, the following second paragraph is not detected as being code: in other words one could do the following and plugin whatever Estimator object one wanted to, as in the following example: bestGuessAtThresh = 10.0 ISI = 300 validresponse = KeySet('y', 'n') Is there a 'moral equivalent' to \begin{verbatim} or
? =)

Thanks.  This is shaping up.

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________

From MHammond@skippinet.com.au  Thu Jan 23 23:49:35 1997
From: MHammond@skippinet.com.au (Mark Hammond)
Date: Fri, 24 Jan 1997 09:49:35 +1000
Subject: [PYTHON DOC-SIG] ni and gendoc
Message-ID: <199701232251.JAA09022@minotaur.labyrinth.net.au>

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@skippinet.com.au 
Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc
 & 

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________

From MHammond@skippinet.com.au  Fri Jan 24 05:28:26 1997
From: MHammond@skippinet.com.au (Mark Hammond)
Date: Fri, 24 Jan 1997 15:28:26 +1000
Subject: [PYTHON DOC-SIG] gendoc, etc.
Message-ID: <199701240429.PAA28705@minotaur.labyrinth.net.au>

 
> 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@skippinet.com.au 
Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc
 & 

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________

From dlarsson@sw.seisy.abb.se  Fri Jan 24 12:26:06 1997
From: dlarsson@sw.seisy.abb.se (Daniel Larsson)
Date: Fri, 24 Jan 1997 13:26:06 +0100
Subject: [PYTHON DOC-SIG] ni and gendoc
References: <199701232251.JAA09022@minotaur.labyrinth.net.au>
Message-ID: <32E8AA5E.2481@sw.seisy.abb.se>


------------64881FD74E943
Content-Transfer-Encoding: 7bit
Content-Type: text/plain; charset=us-ascii

 Mark Hammond wrote:
>
> 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.

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".

--
Daniel

------------64881FD74E943
Content-Transfer-Encoding: 7bit
Content-Type: text/html; charset=us-ascii



 Mark Hammond wrote:

> 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.

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".
 
--
Daniel
------------64881FD74E943-- _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From friedric@rose.rsoc.rockwell.com Fri Jan 24 15:53:20 1997 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Fri, 24 Jan 1997 09:53:20 -0600 Subject: [PYTHON DOC-SIG] gendoc, etc. Message-ID: <199701241553.JAA08759@darwin.rsoc.rockwell.com> |> From: "Mark Hammond" |> 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@python.org administrivia to: doc-sig-request@python.org _______________ From friedric@rose.rsoc.rockwell.com Fri Jan 24 13:56:32 1997 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Fri, 24 Jan 1997 07:56:32 -0600 Subject: [PYTHON DOC-SIG] gendoc, etc. Message-ID: <199701241356.HAA08696@darwin.rsoc.rockwell.com> 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@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Tue Jan 28 00:11:18 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Tue, 28 Jan 1997 10:11:18 +1000 Subject: [PYTHON DOC-SIG] Links to other internal functions/classes? Message-ID: <199701272313.KAA17558@minotaur.labyrinth.net.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... 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@skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc & _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Tue Jan 28 00:11:18 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Tue, 28 Jan 1997 10:11:18 +1000 Subject: [PYTHON DOC-SIG] ni and gendoc Message-ID: <199701272313.KAA17559@minotaur.labyrinth.net.au> > 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@skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc & _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From friedric@rose.rsoc.rockwell.com Mon Jan 27 23:42:34 1997 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Mon, 27 Jan 1997 17:42:34 -0600 Subject: [PYTHON DOC-SIG] Links to other internal functions/classes? Message-ID: <199701272342.RAA11250@darwin.rsoc.rockwell.com> |> From: "Mark Hammond" |> |> 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@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Wed Jan 29 22:52:14 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Thu, 30 Jan 1997 08:52:14 +1000 Subject: [PYTHON DOC-SIG] Who is hacking? Message-ID: <199701292153.IAA01852@minotaur.labyrinth.net.au> 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@skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc & _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From dlarsson@sw.seisy.abb.se Wed Jan 29 22:09:12 1997 From: dlarsson@sw.seisy.abb.se (Daniel Larsson) Date: Wed, 29 Jan 1997 23:09:12 +0100 Subject: [PYTHON DOC-SIG] Who is hacking? References: <199701292153.IAA01852@minotaur.labyrinth.net.au> Message-ID: <32EFCA88.2BA1@sw.seisy.abb.se> ------------79A0463356543 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=us-ascii Mark Hammond wrote: > > 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? I have done most of the implementation, with Robin being the main user so far (as far as I know) sending me bug fixes every so often. > 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 :-) Hmm, well, not really. I made a simple test case, which I think is distributed with the package. If you make enhancements, I'll be more than happy to incorporate them into my source and future releases of gendoc. > My main focusses at the moment are: > * Make it generate a hierarchical index for an "ni" package (my > previous hacks generates a "flat" index. Excellent! > * 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. Sounds great! ------------79A0463356543 Content-Transfer-Encoding: 7bit Content-Type: text/html; charset=us-ascii
Mark Hammond wrote:

> 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?

I have done most of the implementation, with Robin being the main user so far
(as far as I know) sending me bug fixes every so often.

> 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 :-)

Hmm, well, not really. I made a simple test case, which I think is distributed
with the package. If you make enhancements, I'll be more than happy to incorporate
them into my source and future releases of gendoc.

> My main focusses at the moment are:
> * Make it generate a hierarchical index for an "ni" package (my
> previous hacks generates a "flat" index.
 
Excellent!

> * 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.

Sounds great!
 
------------79A0463356543-- _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From dlarsson@sw.seisy.abb.se Wed Jan 29 22:13:36 1997 From: dlarsson@sw.seisy.abb.se (Daniel Larsson) Date: Wed, 29 Jan 1997 23:13:36 +0100 Subject: [PYTHON DOC-SIG] Who is hacking? References: <199701292153.IAA01852@minotaur.labyrinth.net.au> Message-ID: <32EFCB90.1D6F@sw.seisy.abb.se> ------------B69431622A4 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=us-ascii Hmm, I forgot to mention that Martin Chilvers (another australian!) wrote something called "docco", a package similar to gendoc, from which I stole the parsing mode stuff. Thanks to his very modular code this was a piece of cake. ------------B69431622A4 Content-Transfer-Encoding: 7bit Content-Type: text/html; charset=us-ascii
Hmm, I forgot to mention that Martin Chilvers (another australian!) wrote something called "docco", a package similar to gendoc, from which I stole the parsing mode stuff. Thanks to his very modular code this was a piece of cake.
------------B69431622A4-- _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From kryee@wheat.uwaterloo.ca Thu Jan 30 02:20:41 1997 From: kryee@wheat.uwaterloo.ca (Ka-Ping Yee) Date: Wed, 29 Jan 1997 21:20:41 -0500 Subject: [PYTHON DOC-SIG] Who is hacking? Message-ID: <9701300220.AA19749@wheat> 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@python.org administrivia to: doc-sig-request@python.org _______________