Laurent Gautier wrote: > 2007/1/6, Ron Adam <[EMAIL PROTECTED]>: >> Laurent Gautier wrote:
> [...] > I read your comment about having not too many things changed for 2.6. > (or that will be bumped to 3000). > > A suggestion I would have would be to create an html/htmlrender module > in the pydoc-package-to-be and start putting all the html formatting > function > (as they are completely independent of pydoc, as far as I can see, over > there). There really isn't as many html specific formatting functions as you might think since I used a very consistent format of css tagged definition lists. In the case of cgitb, it's probably better to copy those functions to it and just get rid of the dependency. If someone does put together a library of useful html functions and class's then pydoc, cgitb and other programs can use it. BTW, all the html specific functions and formatting have already been collected in the gethtml.py file. I've also added more comments to both gettext.py and gethtml.py last night, so it should be easier to see how it works. First look though gettext.py to get a general idea of how the info is collected and formatted in text, then look at gethtml.py. http://ronadam.com/dl/_pydoc.zip > You can then create wrappers to the original functions including a > deprecation > warning. You can refer to Michael Chermside's recipe for an example of > implementation with a deprecation decorator - > http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/391367 > ) > The suggestion above would actually apply to *anything* that is changed > in pydoc, providing the benefit of allowing the necessary changes while > having > a temporary API to provide back-compatibility. Yes, that would be good and may be needed, but it's still a ways off. Lets get it to work first, then if it gets approved for inclusion, then how to move it into the python distribution (with any needed changes needed for that) can be worked out. First things first, if you know what I mean. > [...] >> > I do not think it will work as a zip file shuttled around (in my >> > experience). >> > A versioning system would be extremely helpful (SVN, or CVS. would >> > come to my mind). >> > Well, if you are ok with having the source tree hosted in a >> > SVN/CVS/alike I am on >> > (opening an account on sourceforge or savannah -for example- would be >> > the next step then, as it can take few days for a project to be >> > approved) >> >> I don't have any experience with SVN, but it could be an opportunity >> to learn >> something new. I have a couple of other projects that could benefit >> by moving >> them to SVN or CVS like system. > > I have seen A.M.Kuching's suggestion about python's sandbox, > but I do not know if it would work in the short term. Anyway, > and at least for the long(er) term, it will make sense to favor SVN > over CVS (since this is what the python project is using). That rules > out savannah and leaves us with sourceforge. I'd like to know more about using the sandbox, I know it would be easy for people to read the source there, but who all can have write access to it without having write access to other python areas? I would not mind giving that a try if someone who already knows how could point me to the correct how-to documentation with some advice on what not to do. I'm actually more concerned about the what not to do stuff. I really would not like to clobber someone else's work or create problems because of my inexperience with CVS. >[...] >> If someone who has more experience with group projects would like to >> manage it, >> that would be good too. That may speed things up considerably. > > I have some experience in it (in companies, and in an open source project) > I can always file a application for a sourceforge project, > and can help you with managing it until you feel like taking it on your own > (or it is merged with the python trunk) I don't see this as taking a long time if we keep it to cleaning up with some API and user interface improvements. I know there are some here who want a smart parsing engine, which probably would take a long term commitment to maintain and fix bugs, etc. But lets look at the actual use's that pydoc serves first. Use's for pydoc in order of importance and frequency of use: 1. Console (builtin) help. ie.. the help() function. 2. HTML browsing and quick reference. 3. Document generation in text. 4. Document generation in html. 5. Document generation in other formats. (not currently possible) I'm concentrating on 1 and 2. Use cases 3 and 4 are just an easy to do byproduct of doing 1 and 2. I think the cleaning up may make doing 5 possible. Lets turn the question around. How well would other document generators supply pydoc with the equivalent text of the help() function, interactive help session output, and the equivalent html needed for dynamic html browsing? Also keep in mind the help function is always by default imported into python, so keeping that small and relatively simple with a minimum of external dependencies is good. > I am willing to contribute to the implementation (I suspect that > things like unit tests be needed). Yes, there will need to be some unit tests. It may even help for those be written now. That would help us identify things that still need to be done. [...] > I should have the time during the week-end. I will get back to you > off-list. Cool. :-) Cheers, Ron _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com