Bug 632554

Chen Lei, are you reviewing this?  I need it to enable unittests/optional features on another package so I'd be willing to review it if you want.  (The required packages have just been approved so I'm just figuring out if I should do this in the next few days or not.)

(In reply to comment #1)
> Chen Lei, are you reviewing this?  I need it to enable unittests/optional
> features on another package so I'd be willing to review it if you want.  (The
> required packages have just been approved so I'm just figuring out if I should
> do this in the next few days or not.)

Free feel to review it :), I'll help to review other python-zope-* packages.

Good:
* Package named according to the packaging guidelines
* Spec matches package name
* License is ZPLv2.1 in source and spec
* License file included in doc
* spec file readable
* Source matches upstream
* No locale specific files
* Not a shared library
* No bundled libraries
* Not relocatable
* Owns the files and direectories it creates and nothing more
* Permissions set properly
* Consistent use of macros
* code, not content.
* Not a GUI
* All filenames UTF-8
* builds in koji

NEEDSWORK:
* Documentation *.txt files in the module directory.  These should go to
  %docdir

rpmlint:
python-zope-component.src: W: no-cleaning-of-buildroot %install
python-zope-component.src: W: no-cleaning-of-buildroot %clean
python-zope-component.src: W: no-buildroot-tag
python-zope-component.src: W: no-%clean-section
2 packages and 0 specfiles checked; 0 errors, 4 warnings

You've been moving the *.txt files to %doc fine in the other zope packages so
I'll approve this and you can move them to %docdir when you import.

APPROVED

(In reply to comment #3)
> 
> NEEDSWORK:
> * Documentation *.txt files in the module directory.  These should go to
>   %docdir
> 
> 
> You've been moving the *.txt files to %doc fine in the other zope packages so
> I'll approve this and you can move them to %docdir when you import.
> 


It seems those files are not very useful if we put them into %{_docdir}, they are normally introductions for some particular files not introductions for the whole packages.

rpm -ql python|grep txt, you'll find python itself also add some txt files to module dir. 

e.g. fields.txt in zope.schema - it's a description for zope/schema/field.py, so it'll be much better to just leave them on module dir.

They do no good in the modules directory -- no one is expecting to look for them there.  So if they aren't doing any good in %{_docdir} then you might as well just rm them.

To me they look like they're documenting usage of the API, though, which could be useful.  In your prior package it seemed like you were recreating part of the directory structure so it seemed that people wanting to know how to use the API were able to see which file mapped to which module.

Bug opened for the main python package:
  https://bugzilla.redhat.com/show_bug.cgi?id=634809

(In reply to comment #5)
> They do no good in the modules directory -- no one is expecting to look for
> them there.  So if they aren't doing any good in %{_docdir} then you might as
> well just rm them.
> 
> To me they look like they're documenting usage of the API, though, which could
> be useful.  In your prior package it seemed like you were recreating part of
> the directory structure so it seemed that people wanting to know how to use the
> API were able to see which file mapped to which module.

It seems moving all .txt files to %{_docdir}/%{name}-%{version} directly is inappropriate.

Take python-zope-schema for a example:

./README.txt
./src/zope/schema/README.txt
./src/zope/schema/sources.txt
./src/zope/schema/index.txt
./src/zope/schema/validation.txt
./src/zope/schema/fields.txt
./CHANGES.txt
./LICENSE.txt
./COPYRIGHT.txt

The contents of ./README.txt and ./src/zope/schema/README.txt are different, we should not override ./README.txt with ./src/zope/schema/README.txt. 

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. 

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. 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.

[1]
e.g.

%{_docdir}/python-zope-schema-%{version}/zope/schema

%{_docdir}/python-%{version}/idlelib


[2]
e.g.

cat /usr/lib/python2.7/site-packages/README
This directory exists so that 3rd party packages can be installed
here.  Read the source for site.py for more details.

(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.

Thanks for you both.

New Package SCM Request
=======================
Package Name: python-zope-component
Short Description: Zope Component Architecture
Owners: cheeselee
Branches: el5 el6 f13 f14
InitialCC:

Git done (by process-git-requests).

Package Change Request
======================
Package Name: python-zope-component
New Branches: epel7
Owners: ralph

Git done (by process-git-requests).