[Bug 632554] Review Request: python-zope-component - Zope Component Architecture

[bugzilla at redhat.com]

Please do not reply directly to this email. All additional
comments should be made in the comments box of this bug.


https://bugzilla.redhat.com/show_bug.cgi?id=632554

--- Comment #8 from Toshio Ernie Kuratomi <a.badger at gmail.com> 2010-09-17 11:34:59 EDT ---
(In reply to comment #7)
> 
> It seems moving all .txt files to %{_docdir}/%{name}-%{version} directly is
> inappropriate.
> 
Agreed because of conflicting file.
> 
> From fields.txt - "This document highlights unusual and subtle aspects of
> various fields and field classes, and is not intended to be a general
> introduction to schema fields.", so obviously this .txt file is not a API docs
> for zope.schema package. It's normally useful when the developer want to take a
> look at the code of the fields.py. 
>
It's normally useful when a developer wants to make use of that API and it is
not behaving the way they expect.  To me this is API documentation.... just not
complete API documentation (ie: it tells how to use the API in complex cases,
not in the easy, normal case.)

> I'm not sure if it'll be clearer to recreate the directory structure under
> %{_docdir}[1] than just leaving those .txt files under module directory. 
> It looks like those directory structures[1] are a bit complicated.

My view is that /usr/share/doc is where people look for documentation...
anything helpful for them to read should be placed there.  %{python_sitelib} is
not the place where people look for documentation so things that are helpful
for users to read should not be left there.

> I don't
> intend to oppose moving text files to %{_docdir}, however I think leaving some
> text files under python module directories is necessary and helpful[2].
> Personally, I think leaving text files under %{_libdir}/python2.x/idlelib is
> reasonable.
> 
Looking over idlelib; the txt files appear to be data that is used within
idle's help system so yes, those are necessary to the runtime operation of idle
and belong in that directory and should not be marked %doc.

/me updates python bug so that that is not overlooked.

-- 
Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.