that library reference, again

classic Classic list List threaded Threaded
32 messages Options
12
Reply | Threaded
Open this post in threaded view
|

that library reference, again

Fredrik Lundh
as seen on the doc-sig:

> > > javadoc's
> > >
> > >     {@link os.popen}
> > >
> > > is even shorter.
> > >
> > > hmm.  maybe a combination of rest/html/whatever and pythondoc markup
> > > would be the ultimate tool for the library reference...
> >
> > <* heavy clapping sound of my footsteps while running away screaming in fear *>
>
> really?

since everything that has people running in fear is worth investigating
further, I've spent a few hours putting together a first iteration of a
"python.org library reference to a javadoc-ish source format converter".

more info here:

    http://effbot.org/zone/pythondoc-lib.htm

including goals, non-goals, and 2.5 megabytes of converted (but not
yet properly rendered) library pages.

</F>



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

bcannon@gmail.com
On 12/26/05, Fredrik Lundh <[hidden email]> wrote:

> as seen on the doc-sig:
>
> > > > javadoc's
> > > >
> > > >     {@link os.popen}
> > > >
> > > > is even shorter.
> > > >
> > > > hmm.  maybe a combination of rest/html/whatever and pythondoc markup
> > > > would be the ultimate tool for the library reference...
> > >
> > > <* heavy clapping sound of my footsteps while running away screaming in fear *>
> >
> > really?
>
> since everything that has people running in fear is worth investigating
> further, I've spent a few hours putting together a first iteration of a
> "python.org library reference to a javadoc-ish source format converter".
>
> more info here:
>
>     http://effbot.org/zone/pythondoc-lib.htm
>
> including goals, non-goals, and 2.5 megabytes of converted (but not
> yet properly rendered) library pages.
>

Not specifically advocating the solution, but the markup looks
reasonable and easy to use.  Thanks for taking a stab at this, /F.

-Brett
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: that library reference, again

Fredrik Lundh
In reply to this post by Fredrik Lundh
I wrote:

> since everything that has people running in fear is worth investigating
> further, I've spent a few hours putting together a first iteration of a
> "python.org library reference to a javadoc-ish source format converter".
>
> more info here:
>
>     http://effbot.org/zone/pythondoc-lib.htm
>
> including goals, non-goals, and 2.5 megabytes of converted (but not
> yet properly rendered) library pages.

I've spent a few more hours tweaking the converter, and I'm now very
close to a point where the entire library reference can be handled by a
combination of this tool and a reasonable manual cleanup effort.

overview:

    http://effbot.org/zone/pythondoc-lib.htm

sample pages (with visible preliminary markup):

    http://effbot.org/lib

however, given that the discussion that led up to this has been dead for
almost a week, I'm beginning to fear that I've wasted my time on a project
that nobody's interested in.  are we stuck with latex for the foreseeable
future?

</F>



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

David Goodger
On 12/29/05, Fredrik Lundh <[hidden email]> wrote:
> however, given that the discussion that led up to this has been dead for
> almost a week,

You mean since Christmas?

> I'm beginning to fear that I've wasted my time on a project
> that nobody's interested in.

Could be. I don't see HTML+PythonDoc as a significant improvement
over LaTeX.

Yes, I'm biased. So are you.

> are we stuck with latex for the foreseeable future?

Until we have something clearly and significantly better, yes.

--
David Goodger <http://python.net/~goodger>
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

Fredrik Lundh
David Goodger wrote:

> > however, given that the discussion that led up to this has been dead for
> > almost a week,
>
> You mean since Christmas?
>
> > I'm beginning to fear that I've wasted my time on a project
> > that nobody's interested in.
>
> Could be. I don't see HTML+PythonDoc as a significant improvement
> over LaTeX.

Really?  Have you read my list of goals?  Does LaTeX address all of them?
Does ReST?  If not, can you explain why they're not important.

> Yes, I'm biased. So are you.

I don't think you understand the problem, so your bias is irrelevant.  This is
all about semantics, not presentation markup.  All I've seen from the ReST
camp is handwaving, there's nothing in the documentation that indicates that
semantic markup has ever been a design goal in ReST, and nobody I've talked
to who've tried using ReST for rich semantic markup considers it to be an
alternative.  This isn't about bias, this is about technical suitability.

If you think otherwise, I suggest you put pick a couple of typical document
pages and show how they would look in ReST, how the corresponding semantic
model will look (and when I say semantic, I mean in Python terms, not in ReST
presentation terms), and how to get from LaTeX to ReST+semantics and HTML+
semantics without having to rewrite everything from scratch.

We know that you have big hats over in ReST-land; now show us some cattle.

</F>



_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

David Goodger
[Fredrik Lundh]
>>> I'm beginning to fear that I've wasted my time on a project
>>> that nobody's interested in.

[David Goodger]
>> Could be. I don't see HTML+PythonDoc as a significant improvement
>> over LaTeX.

[Fredrik Lundh]
> Really?

Yes, really.

> Have you read my list of goals?

Yes, and I mostly agree with most of them.  One is worded in a very
slanted way:

    * Build on existing non-Python-specific documentation standards
      and tools, where possible (basic html, javadoc, xhtml modules,
      etc).

It seems that this goal is specifically written to exclude ReST.
Javadoc is only a standard in the Java world.  LaTeX *is* an
existing language-independent standard, and has a much longer
history than javadoc.

I'd re-write the above goal as:

    * Build on existing documentation standards and tools, where
      possible.

Another goal is highly biased toward XML-style markup:

    * Make it trivial to do basic rendering to HTML (a few re.sub
      calls should suffice), to enable simple tools (CGI scripts, etc)
      to be able to render reference documentation.

This is the tail wagging the dog.

This item is under-specified:

    * Make is easy to do advanced rendering to HTML, XHTML or XML
      models (e.g. typographic issues, navigation, dynamic styling,
      etc.). No more -- dashes and silly ``quotes''.

The second sentence lacks a rationale.  What's wrong with "-- dashes"?
What's "silly" about "``quotes''"?

Your list is missing an important goal:

    * Easy to read.

The final paragraph of the "Project Goals" section lacks context and
contains a false statement:

    The semantic model should be simple, python-oriented, and more
    detailed than today.  For example, while a ReST-based solution
    knows that open in a given context should be rendered in bold, and
    a LaTeX-based solution knows that the given open is a function,
    the PythonDoc model also knows that it refers to the os.open
    function, rather than the built-in open function.

The reference to ReST is wrong here; ReST certainly can know the
semantics of a given identifier.  I'd like to see an example of how
the HTML+PythonDoc markup indicates that a particular "open" is
os.open and not __builtins__.open.

> Does LaTeX address all of them?

Perhaps not.  So?  It works well enough.

> Does ReST?

Not currently, but so what?  I didn't propose ReST as an alternative
to LaTeX for Python's documentation.  All I'm saying is that the
proposed HTML+PythonDoc markup is not significantly better than the
status quo.  I don't think there's enough benefit to make leaving
LaTeX worthwhile.

IOW: -1 on replacing LaTeX with HTML+PythonDoc.

> If not, can you explain why they're not important.
>
>> Yes, I'm biased. So are you.
>
> I don't think you understand the problem, so your bias is
> irrelevant.  This is all about semantics, not presentation markup.

I don't think you understand ReST except superficially.  In any case,
ReST is irrelevant to this discussion.  I do not consider ReST a
suitable replacement for LaTeX in Python's docs at present.

My bias is simple: I am against wasting the time and effort required
to replace one form of verbose markup with a different but equivalent
form.  The proposed solution is no better than the status quo.  I
agree with the people who have stated that they find the direct
writing of HTML painful.

IMO, the markup itself is almost irrelevant.  As others have stated,
writing good documentation is hard.  People will latch on to any
excuse to avoid it, and markup is convenient.  But even if the docs
had no markup whatsoever, if they were written in plain text like
RFCs, I doubt there would be significantly more patch contributions.
Plain text patches are already accepted; perhaps this fact needs more
emphasis, but that's all.

> We know that you have big hats over in ReST-land; now show us some
> cattle.

Moo.  Or would you prefer the Buddhist "mu"?
What *are* you talking about?

--
David Goodger <http://python.net/~goodger>


_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com

signature.asc (257 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

Robey Pointer

On 29 Dec 2005, at 18:58, David Goodger wrote:

> [Fredrik Lundh]
>>>> I'm beginning to fear that I've wasted my time on a project
>>>> that nobody's interested in.
>
> [David Goodger]
>>> Could be. I don't see HTML+PythonDoc as a significant improvement
>>> over LaTeX.
>
> [Fredrik Lundh]
>> Really?
>
> Yes, really.

Just out of curiosity (really -- not trying to jump into the flames)  
why not just use epydoc?  If it's good enough for 3rd-party python  
libraries, isn't that just a small step from being good enough for  
the builtin libraries?

robey

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

Fredrik Lundh
Robey Pointer wrote:
> > [Fredrik Lundh]
> >> Really?
> >
> > Yes, really.
>
> Just out of curiosity (really -- not trying to jump into the flames)
> why not just use epydoc?  If it's good enough for 3rd-party python
> libraries, isn't that just a small step from being good enough for
> the builtin libraries?

but epydoc is a docstring-based format, right?

I'm trying to put together a light-weight alternative to the markup
used for, primarily, the current library reference.

moving all of (or parts of) the reference documentation in to the
library source code would be an alternative, of course [1], but that
would basically mean starting over from scratch.

(but tighter integration is on my list; with a better semantic markup,
you can "import" reference documentation into a module's docstrings
at runtime, the builtin help can point you directly to the documentation
for a given class, etc.).

</F>

1) I'm using a mix of wiki-based introductions and machine generated
markup for e.g. the Tkinter manual; an example:

         http://effbot.org/tkinterbook/listbox.htm



_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

Fredrik Lundh
In reply to this post by David Goodger
> [David Goodger]
> >> Could be. I don't see HTML+PythonDoc as a significant improvement
> >> over LaTeX.
>
> [Fredrik Lundh]
> > Really?
>
> Yes, really.

Your reply makes it obvious that you don't understand the issues involved
here, nor how the goals address them.

(Snipping heavily below due to lack of time; if you want some other argument
refuted, you have to repost and wait until next week.)

> Another goal is highly biased toward XML-style markup:
>
>     * Make it trivial to do basic rendering to HTML (a few re.sub
>       calls should suffice), to enable simple tools (CGI scripts, etc)
>       to be able to render reference documentation.
>
> This is the tail wagging the dog.

No, it's a fundamental goal: to support light-weight generation of rendered
markup directly from source code, to enable simple tools (CGI scripts, etc)
to be able to render reference documentation.

The issue this is addressing is that the current workflow is way too heavy;
when I made my first post, it typically took 3-6 months for a contribution to
the documentation to appear on python.org.  Thanks to Trent and Neal, the
situation is a bit better today, but it's far from ideal.  (More on this below).

> The second sentence lacks a rationale.  What's wrong with "-- dashes"?
> What's "silly" about "``quotes''"?

I'd say that the fact that you're asking this should disqualify you from ever
working on documentation tools again...  don't you know *anything* about
typography ?

> The reference to ReST is wrong here; ReST certainly can know the
> semantics of a given identifier.

> I don't think you understand ReST except superficially.

That's why I'm listening to people who've tried to use ReST for this pur-
pose.  They've all failed.  Maybe they also only understood ReST super-
ficially.  Or maybe it's because ReST is created by people who have a
very shallow understanding of the issues involved in writing structured
reference documentation.  Your guess is as good as mine.

> My bias is simple: I am against wasting the time and effort required
> to replace one form of verbose markup with a different but equivalent
> form.  The proposed solution is no better than the status quo.

Support for quick turnaround, edit via the web, richer semantic information,
and a larger existing toolbase isn't better than the status quo ?

Sounds more like a ReSTian sour-grapes (or scorched-earth) approach
than a serious argument from someone who's interested in improving the
Python documentation.

> IMO, the markup itself is almost irrelevant.  As others have stated,
> writing good documentation is hard.  People will latch on to any
> excuse to avoid it, and markup is convenient.  But even if the docs
> had no markup whatsoever, if they were written in plain text like
> RFCs, I doubt there would be significantly more patch contributions.

The problem is that the WORKFLOW doesn't work.  Quoting from an earlier
post (you have read the earlier discussion, right?):

    If an ordinary user finds a minor issue, a typo, or an error in the
    documentation, the current user workflow is:

    1) (optionally) cut and paste the text to an editor, edit, and save to disk
    2) go to the sourceforge site, and locate the python project
    3) (optionally) sign up for a sourceforge account
    4) log in to your sourceforge account
    5) open a new bug or patch issue, and attach your suggestion
    6) wait 3-6 months for someone to pick up your patch, and for the
       next documentation release to appear on the site

to which can be added:

    If a developer finds a minor issue, a typo, or an error in the documentation,
    the current developer workflow is:

    If logged in to a machine with a full Python development environment:

    1) sync the project
    2) locate the right source file
    3) edit, and save to disk
    4) (optionally) regenerate the documentation and inspect it (3-6 minutes
        if you have the toolchain installed)
    5) commit the change (alternatively, generated a patch; see 2-5 above)
    6) wait up to 12 hours for the updated text to appear on the developer
       staging area on python.org, and 3-6 months for the next documentation
       release to appear on the site

    If no access to a Python development environment:

    1) (optionally) cut and paste the text to an editor, edit, and save to disk
    2) write note or mail to self (or generated a patch; see user instructions
       above)
    3) at an unspecified later time, try to remember what you did, and follow
       the developer instructions above.  wait 3-6 months for the next doc
       release to appear on the site.

I'm not arguing that a change of markup will solve this; I'm saying that a
a light-weight toolchain will make it possible to cut this down to 3-6 seconds
(plus optional moderation overhead for ordinary users).  If people get feedback,
they contribute.

The need for a light-weight markup language follows from this; to eliminate
as much overhead as possible,

 - the semantic model should match the reader's understanding of the
   target domain (in this case, the contents of Python library namespace)
 - the markup closely reflect the underlying semantic model
 - it should be *understandable* and *modifiable* (so you can tweak and
   copy constructs you see in the source, rather than having to look them
   up in a huge reference manual)
 - and it should be easy to parse for both machines and humans.

It's the workflow that's the real problem here, but you cannot fix the workflow
without fixing the markup.

> > We know that you have big hats over in ReST-land; now show us some
> > cattle.
>
> Moo.  Or would you prefer the Buddhist "mu"?
> What *are* you talking about?

I assume this means that we're going to keep getting more "ReST can certainly
do this but we're not going to show anyone how" posts from the ReST camp ?

</F>



_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

Donovan Baarda
I've been dodging this thread because I don't really have much to add,
apart from a documentation end user point of view...

On Fri, 2005-12-30 at 09:25 +0100, Fredrik Lundh wrote:
[...]

> > Another goal is highly biased toward XML-style markup:
> >
> >     * Make it trivial to do basic rendering to HTML (a few re.sub
> >       calls should suffice), to enable simple tools (CGI scripts, etc)
> >       to be able to render reference documentation.
> >
> > This is the tail wagging the dog.
>
> No, it's a fundamental goal: to support light-weight generation of rendered
> markup directly from source code, to enable simple tools (CGI scripts, etc)
> to be able to render reference documentation.

Python is run-time interpreted, but I don't think we need its
documentation to be. "trivial" is a relative term. From my point of
view, provided I can apt-get one or to not-too-esoteric packages then do
something like "make html", it's trivial enough for me.

> The issue this is addressing is that the current workflow is way too heavy;
> when I made my first post, it typically took 3-6 months for a contribution to
> the documentation to appear on python.org.  Thanks to Trent and Neal, the
> situation is a bit better today, but it's far from ideal.  (More on this below).
[...]
> That's why I'm listening to people who've tried to use ReST for this pur-
> pose.  They've all failed.  Maybe they also only understood ReST super-
> ficially.  Or maybe it's because ReST is created by people who have a
> very shallow understanding of the issues involved in writing structured
> reference documentation.  Your guess is as good as mine.

As a some-times developer not really interested in writing
documentation, I must admit I really like ReST. It looks like plain
text, so I can write and use it as plain text, but it also can magically
transform to other formats and look pretty good.

I hate writing XML/HTML, and my only experience with LaTex was brief and
painful too. If I was forced to choose, I'd probably pick LaTex even
though I don't know it as well as XML/HTML (I'd rather face an unknown
evil than that particular devil I know).

> > My bias is simple: I am against wasting the time and effort required
> > to replace one form of verbose markup with a different but equivalent
> > form.  The proposed solution is no better than the status quo.
>
> Support for quick turnaround, edit via the web, richer semantic information,
> and a larger existing toolbase isn't better than the status quo ?
[...]

I'm not going to write docs for stuff I didn't write myself. I'm not
going to submit patches to Javadoc, LaTex or XML/HTML, but I might post
vague "change this to..." bug reports. As an end user, one of the best
things about Python is the on-line documentation... the status-quo looks
pretty good from here.

...but I'm not the person doing it... remember I'm providing a
documentation end-user POV here :-)

> > IMO, the markup itself is almost irrelevant.  As others have stated,
> > writing good documentation is hard.  People will latch on to any
> > excuse to avoid it, and markup is convenient.  But even if the docs
> > had no markup whatsoever, if they were written in plain text like
> > RFCs, I doubt there would be significantly more patch contributions.

Writing good documentation is hard (which is why I prefer to leave it to
others if I can), but fixing almost good documentation doesn't have to
be, and for that, the markup used can make a difference.

As an end user that spots a problem, I'll look at the source, and if
it's in a language I know well enough to fix the problem, I'll submit a
patch. If I find it's in a language I don't know and can't grok well
enough to see how to fix the problem in 10 minutes, I'm going to submit
a verbal description as a bug.

If this is the 5+ time I've stalled on this language, I might consider
learning it so I can do a patch next time. However, in this case the
language in question is a "documentation language" and I want to be a
software programmer, not a document publisher, so I'll probably just
submit bugs every time, and after the 2+ time I won't even bother
looking at the source.

> It's the workflow that's the real problem here, but you cannot fix the workflow
> without fixing the markup.

I must say I disagree with this statement... changing the markup will
not change the workflow at all, just shave 3-6 mins off the compile-test
step. I don't do this enough to really know if that's worth it.

If the markup is changed to something more widely known and/or simple,
more people might participate in the "generate patch" workflow rather
than the "submit bug" workflow, and maybe that will make things easier
for the big picture "update and release docs" workflow. But the speed of
the tool-chain has little to do with this, only the "documentation
language" popularity among the developers and users.

...and if the LaTeX guys don't mind fixing bugs instead of applying
patches and are handling the load... the status quo is fine by me, I'm
happy not to do documentation :-)

--
Donovan Baarda <[hidden email]>
http://minkirri.apana.org.au/~abo/

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

David Goodger
In reply to this post by Fredrik Lundh
[David Goodger]
>> The second sentence lacks a rationale.  What's wrong with "--
>> dashes"?  What's "silly" about "``quotes''"?

[Fredrik Lundh]
> don't you know *anything* about typography ?

Yes, for a layman, I know plenty.  I am not a typographer though.

Simply put, your "list of goals" provides no context for your
statements.  *I* know that "--" is turned into an en-dash in TeX, and
that "``these''" are turned into curly quotes.  So?  What's "silly"
about that?  Spell it out, man!  And what about 99% of the people who
read your page?  They won't know the first thing about what you're
talking about.

>> The reference to ReST is wrong here; ReST certainly can know the
>> semantics of a given identifier.
>
>> I don't think you understand ReST except superficially.
>
> That's why I'm listening to people who've tried to use ReST for this
> purpose.  They've all failed.  Maybe they also only understood ReST
> superficially.

Perhaps, since ReST is *not* designed as a semantic markup language.
It's designed as an implicit markup language, with explicit extensions
for semantic markup.  In any case, ReST is *not* being proposed here.

> Or maybe it's because ReST is created by people who have a very
> shallow understanding of the issues involved in writing structured
> reference documentation.  Your guess is as good as mine.

Why does Fredrik find it necessary to descend to personal insults?
Your guess is as good as mine.

> Support for quick turnaround, edit via the web, richer semantic
> information, and a larger existing toolbase isn't better than the
> status quo ?

Those would be good features.  Those features are not mentioned in
your list of goals though!  (http://effbot.org/zone/pythondoc-lib.htm)
AFAICT, you just went off on a tangent to create a new markup
language, which we don't need.

> The problem is that the WORKFLOW doesn't work.

So fix the workflow.  Something like Ian Bicking's Commentary system,
or something more specific to Python's docs, seems to fit the bill.

> It's the workflow that's the real problem here, but you cannot fix
> the workflow without fixing the markup.

I disagree.  The markup doesn't need an overhaul to fix the workflow.

> I assume this means that we're going to keep getting more "ReST can
> certainly do this but we're not going to show anyone how" posts from
> the ReST camp ?

You assume incorrectly.  I'm not talking about ReST.  I'm not
proposing ReST for anything.  Please ignore the fact that I'm the
author of ReST; I never brought it up, I never proposed it.  *You* are
the one harping on it.

I'm just against an arbitrary and unnecessary change of markup in
Python's docs.

> Your reply makes it obvious that you don't understand the issues
> involved here, nor how the goals address them.

Your reply, and your regular descent to personal insults, make it
excruciatingly obvious that you're a troll.

I hesitated before first replying to this thread, suspecting (from
past experience) that this would be the response I'd get.  From now
on, I'll avoid feeding this particular troll.

> I'd say that the fact that you're asking this should disqualify you
> from ever working on documentation tools again...

Your writing malicious crap like this ought to disqualify you from
ever participating in python-dev discussions again.

Fredrik, we all know that you you are a superb developer who makes
wonderful contributions to Python.  We also know that when faced with
disagreement (and sometimes, seemingly, without any provocation at
all) you are a malicious prick.

--
David Goodger <http://python.net/~goodger>


_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com

signature.asc (257 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

M.-A. Lemburg
In reply to this post by Fredrik Lundh
I haven't followed the thread, so many I'm repeating things.

Has anyone considered using e.g. MediaWiki (the wiki used for
Wikipedia) for Python documentation ?

I'm asking because this wiki has proven to be ideally suited
for creating complex documentation tasks and offers many features
which would make Python documentation a lot easier and more
accessible:

* people wouldn't have to learn LaTeX to commit doc-patches
* it's easy to monitor and revert changes, discuss changes
* there's version history available
* new docs would be instantly available on the web
* builtin search facility, categories and all the other nifty
  wiki stuff
* it's one of the more popular wikis around and due to Wikipedia
  it's here to stay
* conversion to XML and DocBook is possible, providing
  entry points for conversion to other formats (including
  LaTeX)
* more following means more tools (over time)

Just a thought.

Thanks,
--
Marc-Andre Lemburg
eGenix.com

Professional Python Services directly from the Source  (#1, Dec 30 2005)
>>> Python/Zope Consulting and Support ...        http://www.egenix.com/
>>> mxODBC.Zope.Database.Adapter ...             http://zope.egenix.com/
>>> mxODBC, mxDateTime, mxTextTools ...        http://python.egenix.com/
________________________________________________________________________

::: Try mxODBC.Zope.DA for Windows,Linux,Solaris,FreeBSD for free ! ::::
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

ianb
In reply to this post by David Goodger
David Goodger wrote:
>>The problem is that the WORKFLOW doesn't work.
>
>
> So fix the workflow.  Something like Ian Bicking's Commentary system,
> or something more specific to Python's docs, seems to fit the bill.

I'll just note that Commentary works on any HTML, so it doesn't matter
what the original source is written in.

Obviously it is better if the markup of submitted comments match the
original format; but it's unreasonable to accept LaTeX input in comments
and render that to HTML for inline display.  When I have a chance I want
to add ReST input, since some level of markup in comments is really
called for, and I prefer not to create Yet Another Wikiish Markup (and I
like ReST).  But manually translating ReST to LaTeX when integrating
comments is no harder than any other manual translation, and people have
indicated they are willing to do that translation.

Because Commentary writes to flat files, workflow should be fairly
simple -- you submit most updates as comments.  Maybe a login or CAPTCHA
should be added to avoid spam flooding.  rel=nofollow on links is a
no-brainer as well (since unlike a Wiki these are relatively transient
bits of content, so you aren't trapping link information forever by
putting this on all links), but nofollow isn't likely itself to stop spam.

Anyway, submitted comments can be edited by hand through a text editor,
alongside the original documentation, or through the web interface
(right now anyone can delete a comment, but we could restrict that to
documentation maintainers).  If the documentation contains good ids
(that can be traced back to the original source) I think it is
reasonable to do the entire process using the text files (comments are
marked by their relation to a nearby id) -- but the current
documentation has rather meaningless ids, so this might not work.

The flat files can also go in Subversion, with useful diffs and complete
history, living safely in the same repository as the documentation or in
a separate repository.  Comments can be branched or dumped or whatever,
with a workflow parallel to the documentation.  Notification and
tracking tools already exist for Subversion; additional feeds and
whatnot could also certainly be built for Commentary, but it's not clear
that is necessary.

Commentary is still rough in places, but it's pretty much orthogonal to
all the other parts of the documentation system, so it doesn't require
any big investment or conversion process.  Heck, it doesn't even require
buy-in by anyone (except, perhaps, at least one person to generate
comments and one person to consume them), though at some point if it
works well it would be useful to link it from the official
documentation.  But I think it can be useful in a non-official state as
well.

Right now most people who might be willing to contribute to the Python
documentation don't.  Well, "most don't" is an understatement.  "Hardly
any" would be more accurate.  If just a small portion of people could
contribute fairly easily that would be a big step forward.

Anyway, another even more expedient option would be setting up a
separate bug tracker (something simpler to submit to than SF) and
putting a link on the bottom of every page, maybe like:
http://trac.python.org/trac/newticket?summary=re:+/path/to/doc&component=docs 
-- heck, we all know SF bug tracking sucks, this is a good chance to
experiment with a different tracker, and documentation has softer
requirements other parts of Python.


--
Ian Bicking  /  [hidden email]  /  http://blog.ianbicking.org
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

Shane Hathaway
Ian Bicking wrote:
> Right now most people who might be willing to contribute to the Python
> documentation don't.  Well, "most don't" is an understatement.  "Hardly
> any" would be more accurate.  If just a small portion of people could
> contribute fairly easily that would be a big step forward.

+1.  I've often wanted to contribute some small patch to the docs, but
then went back to work and forgot my patch.

Shane
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

Christopher Armstrong-2
In reply to this post by Robey Pointer
On 12/30/05, Robey Pointer <[hidden email]> wrote:

>
> On 29 Dec 2005, at 18:58, David Goodger wrote:
>
> > [Fredrik Lundh]
> >>>> I'm beginning to fear that I've wasted my time on a project
> >>>> that nobody's interested in.
> >
> > [David Goodger]
> >>> Could be. I don't see HTML+PythonDoc as a significant improvement
> >>> over LaTeX.
> >
> > [Fredrik Lundh]
> >> Really?
> >
> > Yes, really.
>
> Just out of curiosity (really -- not trying to jump into the flames)
> why not just use epydoc?  If it's good enough for 3rd-party python
> libraries, isn't that just a small step from being good enough for
> the builtin libraries?

It's not really even "good enough" for a lot of my usage without some
seriously evil hacks. The fundamental design decision of epydoc to
import code, plus some other design decisions on the way it figures
types and identity seriously hinder its utility. Ever notice how
trying to document your third-party-library-using application will
*also* document that third party library, for example? Or how it'll
blow up when you're trying to document your gtk-using application on a
remote server without an X server running? Or how it just plain blows
right up with most Interface systems? etc.

--
  Twisted   |  Christopher Armstrong: International Man of Twistery
   Radix    |    -- http://radix.twistedmatrix.com
            |  Release Manager, Twisted Project
  \\\V///   |    -- http://twistedmatrix.com
   |o O|    |
w----v----w-+
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

Nick Coghlan
In reply to this post by ianb
Ian Bicking wrote:
> Anyway, another even more expedient option would be setting up a
> separate bug tracker (something simpler to submit to than SF) and
> putting a link on the bottom of every page, maybe like:
> http://trac.python.org/trac/newticket?summary=re:+/path/to/doc&component=docs 
> -- heck, we all know SF bug tracking sucks, this is a good chance to
> experiment with a different tracker, and documentation has softer
> requirements other parts of Python.

While I quite like this idea, would it make it more difficult when the bug
tracking for the main source code is eventually migrated off SF? And what
would happen to existing documentation bug reports/patches on the SF trackers?

Is it possible to do something similar for the online version of the current
docs, simply pointing them at the SF tracker? (I know this doesn't help people
without an SF account. . .)

Cheers,
Nick.

--
Nick Coghlan   |   [hidden email]   |   Brisbane, Australia
---------------------------------------------------------------
             http://www.boredomandlaziness.org
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

Laura Creighton
In a message of Sat, 31 Dec 2005 15:41:50 +1000, Nick Coghlan writes:

>Ian Bicking wrote:
>> Anyway, another even more expedient option would be setting up a
>> separate bug tracker (something simpler to submit to than SF) and
>> putting a link on the bottom of every page, maybe like:
>> http://trac.python.org/trac/newticket?summary=re:+/path/to/doc&componen
>t=docs
>> -- heck, we all know SF bug tracking sucks, this is a good chance to
>> experiment with a different tracker, and documentation has softer
>> requirements other parts of Python.
>
>While I quite like this idea, would it make it more difficult when the bu
>g
>tracking for the main source code is eventually migrated off SF? And what
>
>would happen to existing documentation bug reports/patches on the SF trac
>kers?
>
>Is it possible to do something similar for the online version of the curr
>ent
>docs, simply pointing them at the SF tracker? (I know this doesn't help p
>eople
>without an SF account. . .)
>
>Cheers,
>Nick.

Not if the problem is that documentation changes are not 'patches' and
'bugs' and the sourceforge bug tracker, which isn't even particularly
good at tracking bugs is particularly ill-suited for the collaborative
sharing of documents.

Laura

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

ianb
In reply to this post by Nick Coghlan
Nick Coghlan wrote:

>>Anyway, another even more expedient option would be setting up a
>>separate bug tracker (something simpler to submit to than SF) and
>>putting a link on the bottom of every page, maybe like:
>>http://trac.python.org/trac/newticket?summary=re:+/path/to/doc&component=docs 
>>-- heck, we all know SF bug tracking sucks, this is a good chance to
>>experiment with a different tracker, and documentation has softer
>>requirements other parts of Python.
>
>
> While I quite like this idea, would it make it more difficult when the bug
> tracking for the main source code is eventually migrated off SF? And what
> would happen to existing documentation bug reports/patches on the SF trackers?

I think the requirements for documentation are a bit lighter, so it's
not as big a deal.  E.g., the history of bug reports on documentation
isn't as important, either the ones from SF, or if all of Python moves
to a new system then the history of the transitional system.
Documentation is mostly self-describing.

> Is it possible to do something similar for the online version of the current
> docs, simply pointing them at the SF tracker? (I know this doesn't help people
> without an SF account. . .)

Perhaps; I haven't played with the SF interface at all, so I don't know
if you can prefill fields.  But it's still a pain, since logging into SF
isn't seemless (since you don't get redirected back to where you started
from).  Also, I don't know if the requirements for documentation match
the code generally.  Being able to follow up on documentation bugs isn't
as important, so if you don't always collect the submitters email
address it's not that big a deal.  Doc maintainers may be willing to
filter through a bit more spam if it means that they get more
submissions, and so forth.  The review process probably isn't as
important.  So I think it could be argued that code and documentation
shouldn't even be on the same tracker.  (I'm not really arguing that,
but at least it doesn't seem like a big a deal if they aren't on the
same system)

--
Ian Bicking  |  [hidden email]  |  http://blog.ianbicking.org
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

Stephen J. Turnbull
>>>>> "Ian" == Ian Bicking <[hidden email]> writes:

    Ian> Nick Coghlan wrote:

    >> While I quite like this idea, would it make it more difficult
    >> when the bug tracking for the main source code is eventually
    >> migrated off SF? And what would happen to existing
    >> documentation bug reports/patches on the SF trackers?

    Ian> I think the requirements for documentation are a bit lighter,
    Ian> so it's not as big a deal.  E.g., the history of bug reports
    Ian> on documentation isn't as important, either the ones from SF,
    Ian> or if all of Python moves to a new system then the history of
    Ian> the transitional system.

This is almost true, but

    Ian> Documentation is mostly self-describing.

is not.  Python maintains several "supported" releases
simultaneously.  There are important differences between the Python
language and the implementation being discussed on this list
(cPython).  These issues (and their historical tracking) are not
particularly important in the current workflow because most of the
people actually touching the docs are highly experienced experts.
They will get this stuff right more or less naturally, in part because
they're working on documents that are directly associated with a
particular version of a particular implementation.

But as the documentation process moves to a more fluid, user-driven
process, that expertise will be diluted (even with proposals that the
last phase be edited by a dedicated expert, that expert's time
commitment will surely be strained).  That means that history tracking
will become more important, and documentation meta-data (like which
version of which implementation does this change apply to) much more
so.


--
School of Systems and Information Engineering http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
               Ask not how you can "do" free software business;
              ask what your business can "do for" free software.
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] that library reference, again

ianb
In reply to this post by ianb
I've put an instance of Commentary up against the full 2.4
documentation: http://pythonpaste.org/comment/python24/

It writes to a Subversion repository so you can see what the backend
data looks like: http://pythonpaste.org/comment/svn/python24/ -- not
much there yet.  Obviously things like notification and reports would be
useful, but I don't know what the state of the art for Subversion is
either, so potentially these tools already exist.  But last I really
looked at the tools for Subversion, I wasn't overly impressed.  Things
like self-signup for pages you were interested in would be useful.  But
anyway, there's nothing too difficult about those features.

Anyway, it's just meant as a demo for now, but give it a look, and if
you have problems or suggestions write a ticket:
http://pythonpaste.org/commentary/trac/newticket

Cheers.

--
Ian Bicking  |  [hidden email]  |  http://blog.ianbicking.org
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
12