tseaver at palladion
Apr 17, 2012, 12:58 PM
Post #3 of 3
-----BEGIN PGP SIGNED MESSAGE-----
Re: SVN: zope.deprecation/trunk/ Revert a move of `README.txt` to unbreak ``zope.app.apidoc``.
[In reply to]
On 04/17/2012 02:50 PM, Gediminas Paulauskas wrote:
> 2012/4/17 Tres Seaver <tseaver [at] palladion>:
>> -----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
>> 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 Seaver +1 540-429-0999 tseaver [at] palladion
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/
-----END PGP SIGNATURE-----
Zope-Dev maillist - Zope-Dev [at] zope
** No cross posts or HTML encoding! **
(Related lists -