[Pointer] [Doc-SIG] The docs, reloaded (fwd)
Hi all,
There is a very interesting discussion and python-dev and Doc-SIG about
using reST to document python. I think that the ongoing effort to
document numpy and friends with reST could benefit from interaction with
these guys.
Gaël
----- Forwarded message from Georg Brandl
Gael Varoquaux wrote:
Hi all,
There is a very interesting discussion and python-dev and Doc-SIG about using reST to document python. I think that the ongoing effort to document numpy and friends with reST could benefit from interaction with these guys.
Not particularly. They are solving a different problem there: moving from the existing LaTeX system for manual documentation to reST. It doesn't have much to do with docstrings and automatically generated API docs, which is what we've been talking about. -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
On 5/20/07, Robert Kern
Gael Varoquaux wrote:
Hi all,
There is a very interesting discussion and python-dev and Doc-SIG about using reST to document python. I think that the ongoing effort to document numpy and friends with reST could benefit from interaction with these guys.
Not particularly. They are solving a different problem there: moving from the existing LaTeX system for manual documentation to reST. It doesn't have much to do with docstrings and automatically generated API docs, which is what we've been talking about.
It looked like a nice way to generate a manual and was nicely organized and pleasant to look at. For the moment I think we can continue to work on the docstrings but it is good to keep thinking about where it might fit in a larger scheme. It will be interesting to see if anything happens with the interactive patching. Chuck
Charles R Harris wrote:
On 5/20/07, *Robert Kern*
mailto:robert.kern@gmail.com> wrote: Gael Varoquaux wrote: > Hi all, > > There is a very interesting discussion and python-dev and Doc-SIG about > using reST to document python. I think that the ongoing effort to > document numpy and friends with reST could benefit from interaction with > these guys.
Not particularly. They are solving a different problem there: moving from the existing LaTeX system for manual documentation to reST. It doesn't have much to do with docstrings and automatically generated API docs, which is what we've been talking about.
It looked like a nice way to generate a manual and was nicely organized and pleasant to look at. For the moment I think we can continue to work on the docstrings but it is good to keep thinking about where it might fit in a larger scheme. It will be interesting to see if anything happens with the interactive patching.
Chuck
It also provides a path to unified documentation, whether generated from docstrings or manually. # Steve
participants (4)
-
Charles R Harris
-
Gael Varoquaux
-
Robert Kern
-
Steven H. Rogers