[Zope-dev] SVN: zope.deprecation/trunk/ Revert a move of `README.txt` to unbreak ``zope.app.apidoc``.

[Tres Seaver]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 04/17/2012 02:50 PM, Gediminas Paulauskas wrote:
> 2012/4/17 Tres Seaver <tseaver at palladion.com>:
>> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
>> 
>> On 03/15/2012 05:21 AM, Marius Gedminas wrote:
> 
> I have made this change, not Marius.

Oops, sorry for the confusion.

>>> Log message for revision 124600: Revert a move of `README.txt` to 
>>> unbreak ``zope.app.apidoc``.
>>> 
>>> 
>>> Changed: _U  zope.deprecation/trunk/ U 
>>> zope.deprecation/trunk/CHANGES.txt U
>>> zope.deprecation/trunk/README.txt U
>>> zope.deprecation/trunk/setup.py A 
>>> zope.deprecation/trunk/src/zope/deprecation/README.txt
>>> 
>> 
>> I'd like to argue against this reversion:  the ZTK 1.0 / 1.1
>> checkouts should all be using the stable 3.4 branch.  If the
>> z.a.apidoc trunk needs fixing (why in hell does it depend on the
>> existince of a README.txt at package scope in another package?)
>> let's fix it there.
> 
> What if I use ZTK 1.1 but still want zope.app.apidoc (that was
> removed from the set)?

If you use ZTK 1.1, then you should have a version of zope.deprecation
which still has the README.txt in the expected location.  The only
breakage comes when you pick up a newer zope.deprecation.

> The README.txt in project root is not included in the egg.

Yes, it is included:  it just isn't "package data" any longer.

> So I would have to remove 'Zope Deprecation' chapter from the apidoc
> Book and make a new major release of this deprecated module.

I think the whole idea that zope.app.apidoc is the "master documentation"
for all those separately-maintained packages is inherently broken.  We
should be concentrating on writing *real* documentation (via Sphinx),
rather than cobbling together pseudo-documentation via doctests and a
fragile piece of undermaintained code.


> Instead, I restored the location of README.txt, a move that does not 
> have any benefit, so that an app that includes zope.app.apidoc would 
> start, and I do not need to remove any content. Chose lesser evil to 
> fix breakage.

The benefit is to have the top-level README.txt exposed in an "expected"
place (not buried in the software);  the real documentation should be in
a 'docs' subdirectory, buildable with Sphinx.


Tres.
- -- 
===================================================================
Tres Seaver          +1 540-429-0999          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk+Ny2cACgkQ+gerLs4ltQ7kvwCfQbSyyTw3RMVEeUpnE4BH2bod
b10AnjQ2W7owU22XksumnqxPxYbqBwKd
=zYrz
-----END PGP SIGNATURE-----