Is Lore still the official tool for documentation? I've noted that web2 uses reStructuredText. And what about API generation from docstrings? What tool it is used? epydoc? Thanks and regards Manlio Perillo
On Wed, 17 May 2006 13:57:52 -0200, Manlio Perillo
Is Lore still the official tool for documentation?
Yes.
I've noted that web2 uses reStructuredText.
Yes. An experiment, and a failed one. The goal was originally to generate Lore from the ReST; I hope someone will volunteer to translate it to the official format so that it can be included in the PDF with the rest of the documentation.
And what about API generation from docstrings? What tool it is used? epydoc?
Pydoctor. My previous proposal to include pydoctor in lore was met ... coolly, to put it diplomatically ;-).
On Wed, 17 May 2006 13:57:52 -0200, Manlio Perillo
Is Lore still the official tool for documentation?
Yes.
I've noted that web2 uses reStructuredText.
David Reid is working on converting it to lore.
And what about API generation from docstrings? What tool it is used? epydoc?
Michael Hudson wrote an epydoc replacement called pydoctor. It parses the epytext markup in docstrings and generates the API docs now on the website. Jean-Paul
On May 17, 2006, at 11:57 AM, Manlio Perillo wrote:
Is Lore still the official tool for documentation?
Yes.
I've noted that web2 uses reStructuredText.
I did that because I hate lore, but everyone else seems to dislike that I did so, and plans to convert those docs back to lore format. I'd rather that ReST became the recommended doc format, instead of converting those back to lore, but have no free time to try to push that viewpoint.
And what about API generation from docstrings? What tool it is used? epydoc?
No, pydoctor. epydoc doesn't work. James
On Wed, 17 May 2006 12:48:33 -0400, James Y Knight
On May 17, 2006, at 11:57 AM, Manlio Perillo wrote:
I've noted that web2 uses reStructuredText.
I did that because I hate lore, but everyone else seems to dislike that I did so, and plans to convert those docs back to lore format. I'd rather that ReST became the recommended doc format, instead of converting those back to lore, but have no free time to try to push that viewpoint.
FWIW, I really wouldn't be opposed to ReST as a _format_, as long as it fit into the rest of the toolchain. If anyone else shares james' dislike of extremely limited HTML as an input format and user interface[1] to the documentation system, writing an input plugin for lore to recognize it would be a good first step. [1]: I can see why you might. While I personally don't mind typing angle brackets (it's a soothing distraction from all that thinking), Lore's input format was in part a bet that Mozilla Composer would be reasonable and ubiquitous for end-users in a year or two... three years ago. Remember Mozilla? Hee.
On May 17, 2006, at 1:01 PM, glyph@divmod.com wrote:
FWIW, I really wouldn't be opposed to ReST as a _format_, as long as it fit into the rest of the toolchain. If anyone else shares james' dislike of extremely limited HTML as an input format and user interface[1] to the documentation system, writing an input plugin for lore to recognize it would be a good first step.
JP/Exarkun is against ReST as an input format for the documentation system. Writing an input plugin for lore to recognize it isn't a good first step, getting agreement that writing such a plugin would be Good is a good first step. From http://twistedmatrix.com/trac/ticket/ 1515:
All documentation for all Twisted projects should use lore. There should only be one source format for documentation: even though we could write a ReST input driver, doing so would defeat a large portion of the purpose of lore, which is to make it easy to write and maintain documentation (requiring everyone to learn lore xhtml and ReST is harder than requiring everyone to learn lore xhtml). I disagree with that conclusion, but have given up arguing the point. If there are others who support my view, now would be a good time to speak up. You of course get extra bonus points if you've actually contributed to documentation in twisted.
James
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 James Y Knight wrote:
JP/Exarkun is against ReST as an input format for the documentation system. Writing an input plugin for lore to recognize it isn't a good first step, getting agreement that writing such a plugin would be Good is a good first step. From http://twistedmatrix.com/trac/ticket/1515:
All documentation for all Twisted projects should use lore. There should only be one source format for documentation: even though we could write a ReST input driver, doing so would defeat a large portion of the purpose of lore, which is to make it easy to write and maintain documentation (requiring everyone to learn lore xhtml and ReST is harder than requiring everyone to learn lore xhtml).
If I'm not lazy this input driver is going to get written to convert the existing web2 docs anyway. I think he's mainly saying he's against it for the purposes of allowing multiple documentation formats in the source tree. I don't think he'd find it terribly objectionable as a "feature" of lore. Atleast not enough to finding the energy to prevent it from happening.
I disagree with that conclusion, but have given up arguing the point. If there are others who support my view, now would be a good time to speak up. You of course get extra bonus points if you've actually contributed to documentation in twisted.
I just don't see any clear benefit ReST has over lore. Especially not with the amount of existing documentation that is in lore. If anyone would like to point out the benefit I'll gladly listen. - -David - -- "Usually the protocol is this: I appoint someone for a task, which they are not qualified to do. Then, they have to fight a bear if they don't want to do it." -- Glyph Lefkowitz -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.2.2 (Darwin) iD8DBQFEa55orsrO6aeULcgRAilhAJ9s8uA8XuIRrRO/3jMA3s9keUH9JwCgoySY ZTcN7w4Rf2EoF2RKoPajVyI= =LpZH -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Well, I was a contributor to Lore in ages past and was one of the ones who thought it was a great idea. Now I'm in the other camp, and I actually have been using reST for all kinds of documentation on my end. It's just so much more convenient to type. I'm not opposed to saving my documents as HTML-like syntax, but I hate typing angle brackets. After trying out many different approaches, I have decided that my primary requirement in a documentation system is that it be easy to type in documentation. That, and nothing else, keeps me updating my documentation regularly. That and nothing else would convince me to generate more documentation where it's missing. I might be dissuaded if I saw that there was excellent tool support for Lore out there. What tools do people use to write Lore documents? Nvu? How do you handle doing the special lore-specific markup like Python code snippets? - From what I remember about Lore, it doesn't do anything reST can't do; more than that, reST can be converted to Lore without a lot of work. (Round-trip should even be possible, if that was for some reason desirable.) So the bottom line is: It's all about editor preference. I would happily use Nvu if I knew that the output would be Lore without any extra fiddling. C David Reid wrote:
James Y Knight wrote:
JP/Exarkun is against ReST as an input format for the documentation system. Writing an input plugin for lore to recognize it isn't a good first step, getting agreement that writing such a plugin would be Good is a good first step. From http://twistedmatrix.com/trac/ticket/1515:
All documentation for all Twisted projects should use lore. There should only be one source format for documentation: even though we could write a ReST input driver, doing so would defeat a large portion of the purpose of lore, which is to make it easy to write and maintain documentation (requiring everyone to learn lore xhtml and ReST is harder than requiring everyone to learn lore xhtml).
If I'm not lazy this input driver is going to get written to convert the existing web2 docs anyway. I think he's mainly saying he's against it for the purposes of allowing multiple documentation formats in the source tree. I don't think he'd find it terribly objectionable as a "feature" of lore. Atleast not enough to finding the energy to prevent it from happening.
I disagree with that conclusion, but have given up arguing the point. If there are others who support my view, now would be a good time to speak up. You of course get extra bonus points if you've actually contributed to documentation in twisted.
I just don't see any clear benefit ReST has over lore. Especially not with the amount of existing documentation that is in lore. If anyone would like to point out the benefit I'll gladly listen.
-David
-- "Usually the protocol is this: I appoint someone for a task, which they are not qualified to do. Then, they have to fight a bear if they don't want to do it." -- Glyph Lefkowitz
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.2 (MingW32) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFEbKgC3A5SrXAiHQcRAhl/AJ91K/mScJvHmonGM+Cbqpa4S+9gMQCfVKXM wVwd3pIrSD7uTBFyuJntwIo= =r7+i -----END PGP SIGNATURE-----
James Y Knight wrote:
I disagree with that conclusion, but have given up arguing the point. If there are others who support my view, now would be a good time to speak up. You of course get extra bonus points if you've actually contributed to documentation in twisted.
No bonus points for me from contributing much to documentation, but ReST >> Lore. Both because of how nice it is to write and because it's a format with a user base bigger than the number of people who are working on twisted.
James Y Knight ha scritto:
[...]
I've noted that web2 uses reStructuredText.
I did that because I hate lore,
Lore is a good thing, but writing XHTML documents can be a nuisance...
but everyone else seems to dislike that I did so, and plans to convert those docs back to lore format. I'd rather that ReST became the recommended doc format, instead of converting those back to lore, but have no free time to try to push that viewpoint.
What are the problems encountered with reStructuredText?
And what about API generation from docstrings? What tool it is used? epydoc?
No, pydoctor. epydoc doesn't work.
Thanks. The "formats" used are the same, right? I'm asking this because I'm writing a replacement for pgasync. It will be a fully featured client, with an interface like libpq (where this make sense, of course). I'm tring to follow the "twisted way" [1]. I've added unit tests and now I would like to write some documentation. [1] because I think such a thing should be added in twisted.enterprise Regards Manlio Perillo
participants (7)
-
Cory Dodt -
David Reid -
glyph＠divmod.com -
James Y Knight -
Jean-Paul Calderone -
Manlio Perillo -
Tommi Virtanen