Let's turn off api.plone.org.

25 messages

1 2

aclark () Let's turn off api.plone.org.

Reply Threaded

Hi all,

I've got a maintenance scheduled for tonight and cleaning up
is on the brain. To that end I asked Hanno in #plone-framework
about api.plone.org and he said:
11:20 < aclark> hannosch: speaking of Plone, is there any chance in hell
that http://api.plone.org/ will
ever see anything useful or should we just turn it off?
I'd love to think we could put up
some sphinx docs or something there for Plone 4…
11:20 <@hannosch> it won't ever show anything useful
11:20 <@hannosch> there's no Plone API that can be exctracted from the code
11:21 <@hannosch> you either need to look at the full code or follow a specific
tutorial on plone.org/docs
11:21 <@hannosch> you cannot retrofit an API onto this beast anymore

So I'd suggest we turn it off and end the confusion for good! Thoughts?
Further, it would probably make sense to leave a note saying:
Please see the Zope 2 Sphinx docs here: http://docs.zope.org/zope2/zdgbook/source/
and then look in http://plone.org/documentation for specific things.

However, we'll need to be very careful about that as Hanno points out:
11:33 <@hannosch> the Zope2 looks nice, but it tells you to develop Zope2
in the 1990-style. I wouldn't want to point anyone to it
11:33 <@hannosch> some of the stuff about security and the catalog is still
the same, but dtml, python scripts, the OFS nah

Maybe something like:
Please see the relevant Zope 2 Sphinx docs here: http://docs.zope.org/zope2/zdgbook/source/
including:
- TAL
- Security
- Catalog
But you can ignore:
- DTML
- OFS
and then look in http://plone.org/documentation for help with:
- Installing add-ons
- Writing filesystem products
- Etc.
would do it? Anyway, let me know! My feeling is that anything is better than outdated
and useless docs at this point (looking for a flurry of +1s here please ;-).

Alex

--
Alex Clark · http://aclark.net
Buy Practical Plone 3: http://tinyurl.com/practical-plone

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Anne Bowtell-3 () Re: Let's turn off api.plone.org.

Reply Threaded

A "reader's guide" to what's still useful in the Zope 2 book would be
fantastically useful. I often get asked about this - its incredibly
confusing when you're first starting out.

Anne

Alex Clark wrote:

> Hi all,
>
> I've got a maintenance scheduled for tonight and cleaning up
> is on the brain. To that end I asked Hanno in #plone-framework
> about api.plone.org and he said:
> 11:20 < aclark> hannosch: speaking of Plone, is there any chance in hell
> that http://api.plone.org/ will
> ever see anything useful or should we just turn it off?
> I'd love to think we could put up
> some sphinx docs or something there for Plone 4…
> 11:20 <@hannosch> it won't ever show anything useful
> 11:20 <@hannosch> there's no Plone API that can be exctracted from the code
> 11:21 <@hannosch> you either need to look at the full code or follow a specific
> tutorial on plone.org/docs
> 11:21 <@hannosch> you cannot retrofit an API onto this beast anymore
>
> So I'd suggest we turn it off and end the confusion for good! Thoughts?
> Further, it would probably make sense to leave a note saying:
> Please see the Zope 2 Sphinx docs here: http://docs.zope.org/zope2/zdgbook/source/
> and then look in http://plone.org/documentation for specific things.
>
> However, we'll need to be very careful about that as Hanno points out:
> 11:33 <@hannosch> the Zope2 looks nice, but it tells you to develop Zope2
> in the 1990-style. I wouldn't want to point anyone to it
> 11:33 <@hannosch> some of the stuff about security and the catalog is still
> the same, but dtml, python scripts, the OFS nah
>
> Maybe something like:
> Please see the relevant Zope 2 Sphinx docs here: http://docs.zope.org/zope2/zdgbook/source/
> including:
> - TAL
> - Security
> - Catalog
> But you can ignore:
> - DTML
> - OFS
> and then look in http://plone.org/documentation for help with:
> - Installing add-ons
> - Writing filesystem products
> - Etc.
> would do it? Anyway, let me know! My feeling is that anything is better than outdated
> and useless docs at this point (looking for a flurry of +1s here please ;-).
>
> Alex
>
>

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

JoAnna Springsteen () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by aclark

I'm ok with this.

Rephrase note to say:

Please see the relevant Zope 2 documentation here:
http://docs.zope.org/zope2/zdgbook/source
However, please note that the following do not apply to Plone:
- DTML
- OFS
You can find the bulk of Plone documentation at: http://plone.org/documentation

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

David Hostetler () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by aclark

I'd suggest not having any specific information on that landing page at all, if in fact it's not going to ever host anything useful. The example you described is itself information that can and will get stale, compelling someone to maintain it, even if on a very low frequency.

Rather, I'd suggest simply redirecting to a page back on plone.org that gives the short summary you suggested, along with a few relevant links to direct people further. That page can thus be maintained normally, like all other plone.org content.

regards,

-hoss

David Hostetler
[hidden email]

On Wed, Aug 19, 2009 at 11:48, Alex Clark <[hidden email]> wrote:

Hi all,

I've got a maintenance scheduled for tonight and cleaning up
is on the brain. To that end I asked Hanno in #plone-framework
about api.plone.org and he said:
11:20 < aclark> hannosch: speaking of Plone, is there any chance in hell
that http://api.plone.org/ will
ever see anything useful or should we just turn it off?
I'd love to think we could put up
some sphinx docs or something there for Plone 4…
11:20 <@hannosch> it won't ever show anything useful
11:20 <@hannosch> there's no Plone API that can be exctracted from the code
11:21 <@hannosch> you either need to look at the full code or follow a specific
tutorial on plone.org/docs
11:21 <@hannosch> you cannot retrofit an API onto this beast anymore

So I'd suggest we turn it off and end the confusion for good! Thoughts?
Further, it would probably make sense to leave a note saying:
Please see the Zope 2 Sphinx docs here: http://docs.zope.org/zope2/zdgbook/source/
and then look in http://plone.org/documentation for specific things.

However, we'll need to be very careful about that as Hanno points out:
11:33 <@hannosch> the Zope2 looks nice, but it tells you to develop Zope2
in the 1990-style. I wouldn't want to point anyone to it
11:33 <@hannosch> some of the stuff about security and the catalog is still
the same, but dtml, python scripts, the OFS nah

Maybe something like:
Please see the relevant Zope 2 Sphinx docs here: http://docs.zope.org/zope2/zdgbook/source/
including:
- TAL
- Security
- Catalog
But you can ignore:
- DTML
- OFS
and then look in http://plone.org/documentation for help with:
- Installing add-ons
- Writing filesystem products
- Etc.
would do it? Anyway, let me know! My feeling is that anything is better than outdated
and useless docs at this point (looking for a flurry of +1s here please ;-).

Alex

--
Alex Clark · http://aclark.net
Buy Practical Plone 3: http://tinyurl.com/practical-plone

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

aclark () Re: Let's turn off api.plone.org.

Reply Threaded

On 2009-08-19, David Hostetler <[hidden email]> wrote:

> --===============2821822544495789800==
> Content-Type: multipart/alternative; boundary=001485f778da151103047180bc97
>
> --001485f778da151103047180bc97
> Content-Type: text/plain; charset=UTF-8
> Content-Transfer-Encoding: quoted-printable
>
> I'd suggest not having any specific information on that landing page at all=
> ,
> if in fact it's not going to ever host anything useful. The example you
> described is itself information that can and will get stale, compelling
> someone to maintain it, even if on a very low frequency.
>
> Rather, I'd suggest simply redirecting to a page back on plone.org that
> gives the short summary you suggested, along with a few relevant links to
> direct people further. That page can thus be maintained normally, like all
> other plone.org content.

OK That's a great idea, thanks! I whip up a page in http://plone.org/documentation
that we can all edit, then redirect to it.

> regards,
>
> -hoss
>
> David Hostetler
> [hidden email]
>
>
> On Wed, Aug 19, 2009 at 11:48, Alex Clark <[hidden email]> wrote:
>
>> Hi all,
>>
>> I've got a maintenance scheduled for tonight and cleaning up
>> is on the brain. To that end I asked Hanno in #plone-framework
>> about api.plone.org and he said:
>> 11:20 < aclark> hannosch: speaking of Plone, is there any chance in he=
> ll
>> that http://api.plone.org/ will
>> ever see anything useful or should we just turn it off?
>> I'd love to think we could put up
>> some sphinx docs or something there for Plone 4=E2=80=A6
>> 11:20 <@hannosch> it won't ever show anything useful
>> 11:20 <@hannosch> there's no Plone API that can be exctracted from the
>> code
>> 11:21 <@hannosch> you either need to look at the full code or follow a
>> specific
>> tutorial on plone.org/docs
>> 11:21 <@hannosch> you cannot retrofit an API onto this beast anymore
>>
>> So I'd suggest we turn it off and end the confusion for good! Thoughts?
>> Further, it would probably make sense to leave a note saying:
>> Please see the Zope 2 Sphinx docs here:
>> http://docs.zope.org/zope2/zdgbook/source/
>> and then look in http://plone.org/documentation for specific things.
>>
>> However, we'll need to be very careful about that as Hanno points out:
>> 11:33 <@hannosch> the Zope2 looks nice, but it tells you to develop
>> Zope2
>> in the 1990-style. I wouldn't want to point anyone to it
>> 11:33 <@hannosch> some of the stuff about security and the catalog is
>> still
>> the same, but dtml, python scripts, the OFS nah
>>
>> Maybe something like:
>> Please see the relevant Zope 2 Sphinx docs here:
>> http://docs.zope.org/zope2/zdgbook/source/
>> including:
>> - TAL
>> - Security
>> - Catalog
>> But you can ignore:
>> - DTML
>> - OFS
>> and then look in http://plone.org/documentation for help with:
>> - Installing add-ons
>> - Writing filesystem products
>> - Etc.
>> would do it? Anyway, let me know! My feeling is that anything is better
>> than outdated
>> and useless docs at this point (looking for a flurry of +1s here please
>> ;-).
>>
>> Alex
>>
>> --
>> Alex Clark =C2=B7 http://aclark.net
>> Buy Practical Plone 3: http://tinyurl.com/practical-plone
>>
>>
>>
>> -------------------------------------------------------------------------=
> -----
>> Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-D=
> ay
>> trial. Simplify your report design, integration and deployment - and focu=
> s
>> on
>> what you do best, core application coding. Discover what's new with
>> Crystal Reports now. http://p.sf.net/sfu/bobj-july
>> _______________________________________________
>> Plone-docs mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/plone-docs
>>
>
> --001485f778da151103047180bc97
> Content-Type: text/html; charset=UTF-8
> Content-Transfer-Encoding: quoted-printable
>
> I'd suggest not having any specific information on that landing page at=
> all, if in fact it's not going to ever host anything useful.=C2=A0 The=
> example you described is itself information that can and will get stale, c=
> ompelling someone to maintain it, even if on a very low frequency. 
>
> Rather, I'd suggest simply redirecting to a page back on <a href=3D=
> "http://plone.org">plone.org</a> that gives the short summary you suggested=
> , along with a few relevant links to direct people further.=C2=A0 That page=
> can thus be maintained normally, like all other <a href=3D"http://plone.or=
> g">plone.org</a> content. 
>
> regards, -hoss David Hostetler <a href=3D"mailto:negat=
> [hidden email]">[hidden email]</a> <div class=3D"gmail_=
> quote">On Wed, Aug 19, 2009 at 11:48, Alex Clark <<a h=
> ref=3D"mailto:[hidden email]">[hidden email]</a>> wrote:<br=
>>
>
><blockquote class=3D"gmail_quote" style=3D"border-left: 1px solid rgb(204, =
> 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">Hi all, 
> 
> I've got a maintenance scheduled for tonight and cleaning up 
> is on the brain. To that end I asked Hanno in #plone-framework 
> about <a href=3D"http://api.plone.org" target=3D"_blank">api.plone.org</a> =
> and he said: 
> =C2=A0 =C2=A011:20 < aclark> hannosch: speaking of Plone, is there a=
> ny chance in hell 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0that <a href=3D"http://api.plone.org/" target=
>=3D"_blank">http://api.plone.org/</a> will 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0ever see anything useful or should we just turn=
> it off? 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0I'd love to think we could put up 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0some sphinx docs or something there for Plone 4=
>=E2=80=A6 
> =C2=A0 =C2=A011:20 <@hannosch> it won't ever show anything usefu=
> l 
> =C2=A0 =C2=A011:20 <@hannosch> there's no Plone API that can be =
> exctracted from the code 
> =C2=A0 =C2=A011:21 <@hannosch> you either need to look at the full c=
> ode or follow a specific 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0tutorial on <a href=3D"http://plone.org/docs" t=
> arget=3D"_blank">plone.org/docs</a> 
> =C2=A0 =C2=A011:21 <@hannosch> you cannot retrofit an API onto this =
> beast anymore 
> 
> So I'd suggest we turn it off and end the confusion for good! Thoughts?=
> 
> Further, it would probably make sense to leave a note saying: 
> =C2=A0 =C2=A0Please see the Zope 2 Sphinx docs here: <a href=3D"http://doc=
> s.zope.org/zope2/zdgbook/source/" target=3D"_blank">http://docs.zope.org/zo=
> pe2/zdgbook/source/</a> 
> =C2=A0 =C2=A0and then look in <a href=3D"http://plone.org/documentation" t=
> arget=3D"_blank">http://plone.org/documentation</a> for specific things.<br=
>>
> 
> However, we'll need to be very careful about that as Hanno points out:<=
> br>
> =C2=A0 =C2=A011:33 <@hannosch> the Zope2 looks nice, but it tells yo=
> u to develop Zope2 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0in the 1990-style. I wouldn't want to point=
> anyone to it 
> =C2=A0 =C2=A011:33 <@hannosch> some of the stuff about security and =
> the catalog is still 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0the same, but dtml, python scripts, the OFS nah=
> 
> 
> Maybe something like: 
> =C2=A0 =C2=A0Please see the relevant Zope 2 Sphinx docs here: <a href=3D"h=
> ttp://docs.zope.org/zope2/zdgbook/source/" target=3D"_blank">http://docs.zo=
> pe.org/zope2/zdgbook/source/</a> 
> =C2=A0 =C2=A0including: 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0- TAL 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0- Security 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0- Catalog 
> =C2=A0 =C2=A0But you can ignore: 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0- DTML 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0- OFS 
> =C2=A0 =C2=A0and then look in <a href=3D"http://plone.org/documentation" t=
> arget=3D"_blank">http://plone.org/documentation</a> for help with: 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0- Installing add-ons 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0- Writing filesystem products 
> =C2=A0 =C2=A0 =C2=A0 =C2=A0- Etc. 
> would do it? Anyway, let me know! My feeling is that anything is better tha=
> n outdated 
> and useless docs at this point (looking for a flurry of +1s here please ;-)=
> . 
> 
> Alex 
> 
> -- 
> Alex Clark =C2=B7 <a href=3D"http://aclark.net" target=3D"_blank">http://ac=
> lark.net</a> 
> Buy Practical Plone 3: <a href=3D"http://tinyurl.com/practical-plone" targe=
> t=3D"_blank">http://tinyurl.com/practical-plone</a> 
> 
> 
> ---------------------------------------------------------------------------=
> --- 
> Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day=
> 
> trial. Simplify your report design, integration and deployment - and focus =
> on 
> what you do best, core application coding. Discover what's new with 
> Crystal Reports now. =C2=A0<a href=3D"http://p.sf.net/sfu/bobj-july" target=
>=3D"_blank">http://p.sf.net/sfu/bobj-july</a> 
> _______________________________________________ 
> Plone-docs mailing list 
><a href=3D"mailto:[hidden email]">[hidden email]=
> forge.net</a> 
><a href=3D"https://lists.sourceforge.net/lists/listinfo/plone-docs" target=
>=3D"_blank">https://lists.sourceforge.net/lists/listinfo/plone-docs</a> 
></blockquote></div> 
>
> --001485f778da151103047180bc97--
>
>
> --===============2821822544495789800==
> Content-Type: text/plain; charset="us-ascii"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Content-Disposition: inline
>
> ------------------------------------------------------------------------------
> Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
> trial. Simplify your report design, integration and deployment - and focus on
> what you do best, core application coding. Discover what's new with
> Crystal Reports now. http://p.sf.net/sfu/bobj-july
> --===============2821822544495789800==
> Content-Type: text/plain; charset="us-ascii"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Content-Disposition: inline
>
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs
>
> --===============2821822544495789800==--
>
>

--
Alex Clark · http://aclark.net
Buy Practical Plone 3: http://tinyurl.com/practical-plone

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Carsten Senger-3 () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by aclark

Hi Alex,

--On Mittwoch, August 19, 2009 15:48:02 +0000 Alex Clark
<[hidden email]> wrote:

> So I'd suggest we turn it off and end the confusion for good! Thoughts?

I use it regulary as a fast way to grep for a method cause it shows me
where the method is inherited from. I'm ok with turning it off as it isn't
usefull as api documentation. But I like to hear how other people find the
source of a method without jumping through many source files.

..Carsten

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

aclark () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by Anne Bowtell-3

On 2009-08-19, Anne Bowtell <[hidden email]> wrote:
> A "reader's guide" to what's still useful in the Zope 2 book would be
> fantastically useful. I often get asked about this - its incredibly
> confusing when you're first starting out.

Do we have any docs like this in plone.org/documentation? If not, I'm going to
create one now…

>
> Anne
>
> Alex Clark wrote:
>> Hi all,
>>
>> I've got a maintenance scheduled for tonight and cleaning up
>> is on the brain. To that end I asked Hanno in #plone-framework
>> about api.plone.org and he said:
>> 11:20 < aclark> hannosch: speaking of Plone, is there any chance in hell
>> that http://api.plone.org/ will
>> ever see anything useful or should we just turn it off?
>> I'd love to think we could put up
>> some sphinx docs or something there for Plone 4…
>> 11:20 <@hannosch> it won't ever show anything useful
>> 11:20 <@hannosch> there's no Plone API that can be exctracted from the code
>> 11:21 <@hannosch> you either need to look at the full code or follow a specific
>> tutorial on plone.org/docs
>> 11:21 <@hannosch> you cannot retrofit an API onto this beast anymore
>>
>> So I'd suggest we turn it off and end the confusion for good! Thoughts?
>> Further, it would probably make sense to leave a note saying:
>> Please see the Zope 2 Sphinx docs here: http://docs.zope.org/zope2/zdgbook/source/
>> and then look in http://plone.org/documentation for specific things.
>>
>> However, we'll need to be very careful about that as Hanno points out:
>> 11:33 <@hannosch> the Zope2 looks nice, but it tells you to develop Zope2
>> in the 1990-style. I wouldn't want to point anyone to it
>> 11:33 <@hannosch> some of the stuff about security and the catalog is still
>> the same, but dtml, python scripts, the OFS nah
>>
>> Maybe something like:
>> Please see the relevant Zope 2 Sphinx docs here: http://docs.zope.org/zope2/zdgbook/source/
>> including:
>> - TAL
>> - Security
>> - Catalog
>> But you can ignore:
>> - DTML
>> - OFS
>> and then look in http://plone.org/documentation for help with:
>> - Installing add-ons
>> - Writing filesystem products
>> - Etc.
>> would do it? Anyway, let me know! My feeling is that anything is better than outdated
>> and useless docs at this point (looking for a flurry of +1s here please ;-).
>>
>> Alex
>>
>>
>
>
> ------------------------------------------------------------------------------
> Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
> trial. Simplify your report design, integration and deployment - and focus on
> what you do best, core application coding. Discover what's new with
> Crystal Reports now. http://p.sf.net/sfu/bobj-july
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

David Hostetler () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by Carsten Senger-3

grep -Rl "def <method name>" *

If there's a more efficient way I'll adopt it in a heartbeat.

On Wed, Aug 19, 2009 at 12:16, Carsten Senger <[hidden email]> wrote:

Hi Alex,

--On Mittwoch, August 19, 2009 15:48:02 +0000 Alex Clark

<[hidden email]> wrote:

> So I'd suggest we turn it off and end the confusion for good! Thoughts?

I use it regulary as a fast way to grep for a method cause it shows me
where the method is inherited from. I'm ok with turning it off as it isn't
usefull as api documentation. But I like to hear how other people find the
source of a method without jumping through many source files.

..Carsten

aclark () Re: Let's turn off api.plone.org.

Reply Threaded

On 2009-08-19, David Hostetler <[hidden email]> wrote:
> --===============8092464424708246308==
> Content-Type: multipart/alternative; boundary=00163645705e9d43f80471810811
>
> --00163645705e9d43f80471810811
> Content-Type: text/plain; charset=UTF-8
> Content-Transfer-Encoding: 7bit
>
> grep -Rl "def <method name>" *

Yeah, the problem we are facing now (IMO) is api.plone.org
is useful for folks like Carsten that can use it as a
"grep-like" tool (via google searches, I assume), but
otherwise not very useful and more importantly confusing
to new people (i.e. the "OMG! Plone is a monster!" reaction.)
So, like David says, I would suggest developers
use a filesystem grep to (almost as easily) get the same
information, and we spare new people the confusion.

In the future, I'd love to see something like:
http://apidoc.zope.org/++apidoc++/
available for Plone, but I'm not sure what the likelyhood
of that is (I believe Philikon told me once that it could *probably*
be easily implemented in Five, but has not been yet.)

> If there's a more efficient way I'll adopt it in a heartbeat.
>
> On Wed, Aug 19, 2009 at 12:16, Carsten Senger <[hidden email]> wrote:
>
>> Hi Alex,
>>
>> --On Mittwoch, August 19, 2009 15:48:02 +0000 Alex Clark
>> <[hidden email]> wrote:
>>
>> > So I'd suggest we turn it off and end the confusion for good! Thoughts?
>>
>> I use it regulary as a fast way to grep for a method cause it shows me
>> where the method is inherited from. I'm ok with turning it off as it isn't
>> usefull as api documentation. But I like to hear how other people find the
>> source of a method without jumping through many source files.
>>
>> ..Carsten
>>
>>
>
> --00163645705e9d43f80471810811
> Content-Type: text/html; charset=UTF-8
> Content-Transfer-Encoding: quoted-printable
>
> grep -Rl "def <method name>" * If there's a =
> more efficient way I'll adopt it in a heartbeat. <div class=3D"g=
> mail_quote">On Wed, Aug 19, 2009 at 12:16, Carsten Senger ><<a href=3D"mailto:[hidden email]">[hidden email]</a>></span=
>> wrote: 
>
><blockquote class=3D"gmail_quote" style=3D"border-left: 1px solid rgb(204, =
> 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">Hi Alex, 
> 
> --On Mittwoch, August 19, 2009 15:48:02 +0000 Alex Clark 
><div class=3D"im"><<a href=3D"mailto:[hidden email]">[hidden email]=
> t</a>> wrote: 
> 
> > So I'd suggest we turn it off and end the confusion for good! Thou=
> ghts? 
> 
></div>I use it regulary as a fast way to grep for a method cause it shows m=
> e 
> where the method is inherited from. I'm ok with turning it off as it is=
> n't 
> usefull as api documentation. But I like to hear how other people find the<=
> br>
> source of a method without jumping through many source files. 
> 
> ..Carsten 
><div><div></div> </div></blockquote></div> 
>
> --00163645705e9d43f80471810811--
>
>
> --===============8092464424708246308==
> Content-Type: text/plain; charset="us-ascii"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Content-Disposition: inline
>
> ------------------------------------------------------------------------------
> Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
> trial. Simplify your report design, integration and deployment - and focus on
> what you do best, core application coding. Discover what's new with
> Crystal Reports now. http://p.sf.net/sfu/bobj-july
> --===============8092464424708246308==
> Content-Type: text/plain; charset="us-ascii"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Content-Disposition: inline
>
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs
>
> --===============8092464424708246308==--
>
>

claytron () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by Carsten Senger-3

On Aug 19, 2009, at 12:16 PM, Carsten Senger wrote:

> Hi Alex,
>
> --On Mittwoch, August 19, 2009 15:48:02 +0000 Alex Clark
> <[hidden email]> wrote:
>
>> So I'd suggest we turn it off and end the confusion for good!
>> Thoughts?
>
> I use it regulary as a fast way to grep for a method cause it shows me
> where the method is inherited from. I'm ok with turning it off as it
> isn't
> usefull as api documentation. But I like to hear how other people
> find the
> source of a method without jumping through many source files.

I have never used api.plone.org, always seemed to confuse me more in
the past. There are a couple of tools that I use locally:

* ack (or grep) to find things on the filesystem or in TextMate with
ack/grep in project
* collective.recipe.omelette to get all the latest packages in one
place
* DocFinderTab to see how the inheritance structure goes via the ZMI

claytron
--
six feet up, inc. | "Nowhere to go but open source"
Direct Line +1 (317) 861-5948 x603
[hidden email]
http://www.sixfeetup.com | Zope/Plone Custom Development + Hosting

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

--
S i x F e e t U p , I n c . | "Nowhere to go but open source"
Direct Line: +1 (317) 861-5948 x603
Toll-Free: 1-866-SIX-FEET
clayton@sixfeetup.com
http://www.sixfeetup.com | Zope/Plone Custom Development

Dylan Jay-4 () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by aclark

On 20/08/2009, at 2:17 AM, Alex Clark wrote:

> On 2009-08-19, Anne Bowtell <[hidden email]> wrote:
>> A "reader's guide" to what's still useful in the Zope 2 book would be
>> fantastically useful. I often get asked about this - its incredibly
>> confusing when you're first starting out.
>
> Do we have any docs like this in plone.org/documentation? If not,
> I'm going to
> create one now…

I think the closest is in Mikko/collective new developer documentation
even though it's not published on plone.org yet.

https://svn.plone.org/svn/collective/collective.developermanual/trunk/source/introduction/

>
>>
>> Anne
>>
>> Alex Clark wrote:
>>> Hi all,
>>>
>>> I've got a maintenance scheduled for tonight and cleaning up
>>> is on the brain. To that end I asked Hanno in #plone-framework
>>> about api.plone.org and he said:
>>> 11:20 < aclark> hannosch: speaking of Plone, is there any
>>> chance in hell
>>> that http://api.plone.org/ will
>>> ever see anything useful or should we just turn it off?
>>> I'd love to think we could put up
>>> some sphinx docs or something there for Plone 4…
>>> 11:20 <@hannosch> it won't ever show anything useful
>>> 11:20 <@hannosch> there's no Plone API that can be exctracted
>>> from the code
>>> 11:21 <@hannosch> you either need to look at the full code or
>>> follow a specific
>>> tutorial on plone.org/docs
>>> 11:21 <@hannosch> you cannot retrofit an API onto this beast
>>> anymore
>>>
>>> So I'd suggest we turn it off and end the confusion for good!
>>> Thoughts?
>>> Further, it would probably make sense to leave a note saying:
>>> Please see the Zope 2 Sphinx docs here: http://docs.zope.org/zope2/zdgbook/source/
>>> and then look in http://plone.org/documentation for specific
>>> things.
>>>
>>> However, we'll need to be very careful about that as Hanno points
>>> out:
>>> 11:33 <@hannosch> the Zope2 looks nice, but it tells you to
>>> develop Zope2
>>> in the 1990-style. I wouldn't want to point anyone to it
>>> 11:33 <@hannosch> some of the stuff about security and the
>>> catalog is still
>>> the same, but dtml, python scripts, the OFS nah
>>>
>>> Maybe something like:
>>> Please see the relevant Zope 2 Sphinx docs here: http://docs.zope.org/zope2/zdgbook/source/
>>> including:
>>> - TAL
>>> - Security
>>> - Catalog
>>> But you can ignore:
>>> - DTML
>>> - OFS
>>> and then look in http://plone.org/documentation for help with:
>>> - Installing add-ons
>>> - Writing filesystem products
>>> - Etc.
>>> would do it? Anyway, let me know! My feeling is that anything is
>>> better than outdated
>>> and useless docs at this point (looking for a flurry of +1s here
>>> please ;-).
>>>
>>> Alex
>>>
>>>
>>
>>
>> ------------------------------------------------------------------------------
>> Let Crystal Reports handle the reporting - Free Crystal Reports
>> 2008 30-Day
>> trial. Simplify your report design, integration and deployment -
>> and focus on
>> what you do best, core application coding. Discover what's new with
>> Crystal Reports now. http://p.sf.net/sfu/bobj-july
>> _______________________________________________
>> Plone-docs mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/plone-docs
>
>
> --
> Alex Clark · http://aclark.net
> Buy Practical Plone 3: http://tinyurl.com/practical-plone
>
>
> ------------------------------------------------------------------------------
> Let Crystal Reports handle the reporting - Free Crystal Reports 2008
> 30-Day
> trial. Simplify your report design, integration and deployment - and
> focus on
> what you do best, core application coding. Discover what's new with
> Crystal Reports now. http://p.sf.net/sfu/bobj-july
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

Jean Jordaan () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by claytron

> There are a couple of tools that I use locally:
>
> * ack (or grep) to find things on the filesystem or in TextMate with
> ack/grep in project
> * collective.recipe.omelette to get all the latest packages in one
> place
> * DocFinderTab to see how the inheritance structure goes via the ZMI

And ctags together with a proper editor.
http://ctags.sourceforge.net/
http://ctags.sourceforge.net/tools.html

Just run 'ctags -R <omelettedir>'.

--
jean . .. .... //\\\oo///\\

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Israel Saeta Pérez () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by aclark

Alex Clark wrote:

> Hi all,
>
> [...]
> However, we'll need to be very careful about that as Hanno points out:
> 11:33 <@hannosch> the Zope2 looks nice, but it tells you to develop Zope2
> in the 1990-style. I wouldn't want to point anyone to it
> 11:33 <@hannosch> some of the stuff about security and the catalog is still
> the same, but dtml, python scripts, the OFS nah
>
> Maybe something like:
> Please see the relevant Zope 2 Sphinx docs here: http://docs.zope.org/zope2/zdgbook/source/
> including:
> - TAL
> - Security
> - Catalog
> But you can ignore:
> - DTML
> - OFS
> and then look in http://plone.org/documentation for help with:
> - Installing add-ons
> - Writing filesystem products
> - Etc.
> would do it? Anyway, let me know! My feeling is that anything is better than outdated
> and useless docs at this point (looking for a flurry of +1s here please ;-).

I'm +1 on removing the current api.plone.org.

Since some people use it as a grep-like tool, I'd place some ideas here
about how to find the source of a certain method, like using grep (with
an example if possible), collective.recipe.omelette and DocFinderTab.

I'd also provide a link to plone.org/documentation, but no link to the
zope 2 documentation to avoid having to explain which part is updated
and which one isn't.

-- israel

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Israel Saeta Pérez

Israel Saeta Pérez () Re: Let's turn off api.plone.org.

Reply Threaded

Israel Saeta Pérez wrote:
> Since some people use it as a grep-like tool, I'd place some ideas here
> about how to find the source of a certain method, like using grep (with
> an example if possible), collective.recipe.omelette and DocFinderTab.

Ah, and I should also put here a little explanation about _why_ are we
removing the old api.plone.org. :)

-- israel

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Israel Saeta Pérez

Alberto Lopes () Re: Let's turn off api.plone.org.

Reply Threaded

It might be a naive and side question, but since it is related to the discussion, why not include DocFinderTab in the basic Plone installation? It seems pretty small, harmless and it is very useful both for the developer and the administrator sometimes.

2009/8/20 Israel Saeta Pérez <[hidden email]>

Israel Saeta Pérez wrote:
> Since some people use it as a grep-like tool, I'd place some ideas here
> about how to find the source of a certain method, like using grep (with
> an example if possible), collective.recipe.omelette and DocFinderTab.

Ah, and I should also put here a little explanation about _why_ are we
removing the old api.plone.org. :)

-- israel

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Ricardo Newbery-2 () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by claytron

On Aug 19, 2009, at 11:40 AM, Clayton Parker wrote:

> I have never used api.plone.org, always seemed to confuse me more in
> the past. There are a couple of tools that I use locally:
>
> * ack (or grep) to find things on the filesystem or in TextMate with
> ack/grep in project
> * collective.recipe.omelette to get all the latest packages in one
> place
> * DocFinderTab to see how the inheritance structure goes via the ZMI

Ditto. I also still keep BBedit around solely for its unmatched
search and diff capabilities. But unfortunately, the BBedit search
doesn't seem to follow the symbolic links made by omelette :-(

Ric

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Wouter Vanden Hove-2 () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by Dylan Jay-4

Dylan Jay wrote:

> I think the closest is in Mikko/collective new developer documentation
> even though it's not published on plone.org yet.

It could have been, but I regret the decision to not base it on Sphinx.
Nearly all python projects use Sphinx nowadays for *developer*
documentation.

Even Buildout, Zope2, Repoze and other plone-related technologies opt for
Sphinx.

Rok has created very nice Shpinx-plugins
http://sharbas.blogspot.com/2008/11/one-week-of-riding-sphinx.html
http://plone.org/support/forums/core#nabble-td1488503

IMHO api.plone.org should look like this:
http://docs.garbas.si/plone-latest/

-1 on disabling api.plone.org without a better alternative
Disabling public API-information, when the only alternative given is a local
grep??

We should find a way to lower the access to the rst-based docs inside each
plone-package, and IMHO Sphinx is the solution for that.

> My feeling is that anything is better than outdated
> and useless docs at this point

If the versions are clearly mentioned, which is the case here,
then I don't consider it outdated.
It's not updated, and incomplete, but not outdated.
the docs of plone 2.5.5 or 3.0 don't evolve anymore, but they are not
outdated for plone-sites that still run those versions.

It is certainly wrong to assume all plone-website run on the latest released
version. and therefore only docs of that version should publicized.
If api.plone.org was complete for all recent plone-releases, would we have
this discussion?

I have used api.plone.org occasionally in the past,
and Plone definitely needs autogenerated code. Grep is no substitute.
Grep is a poor man's documentation tool.

Let this this situation:
some newbie developer asks by mail a question
about ATNewsitem-schema and how it relates to ATDocument and baseContent

I sent an url like this:
http://api.plone.org/Plone/3.0/public/frames/products/ATContentTypes/products.ATContentTypes.content.newsitem.ATNewsItem-class.html

Now switch off api.plone.org, and send him a grep-command instead? (with
instruction how to install grep on windows probably)

api.plone.org was a very good idea. (ok, maybe API is not the correct word)
the docs on plone.org is not subsitute for autogenerated documentation

> but otherwise not very useful and more importantly confusing
> to new people (i.e. the "OMG! Plone is a monster!" reaction.)

So ... let's obfuscate developer information even further?

question: Do C#/.NET developers need to grep in Microsoft's code to search
how they should program their application?

--
Greets,
WouterVH

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Mikko Ohtamaa () Re: Let's turn off api.plone.org.

Reply Threaded

On Fri, Aug 21, 2009 at 4:06 PM, Wouter Vanden Hove <[hidden email]> wrote:

Dylan Jay wrote:

> I think the closest is in Mikko/collective new developer documentation
> even though it's not published on plone.org yet.

It could have been, but I regret the decision to not base it on Sphinx.
Nearly all python projects use Sphinx nowadays for *developer*
documentation.

(Shh: secret. collective.developermanual runs on Sphinx nowadays. But don't tell anyone ;)

Seriously... manual files are just bunch of restructured text docs. You can very very easily build HTML Sphinx manual offline or publish them in plone.org.

If someone helps me to stick Sphinx index.txt files together and fix some resST errors the manual is good-to-know: https://svn.plone.org/svn/collective/collective.developermanual/trunk/source

I'll plan to create upload script which either pushes docs themselves as reST to plone.org or puts them though Sphinx HTML generator first.

More serious problem regarding the API documentation that the classes itself don't document themselves properly. There won't be API documentation until API is documented.

* All ZCML documentation (apidoc.zope.org) lack examples

* There is no way to generate zope.event event list, since event interfaces don't tell where the event is used

* There is no way to generate event subscriber list

* There is no way to generate stock view list since view classes are uncommented

* and so on...

Autogeneated API docs don't make sense in Plone world until someone, who actually knows the code, goes through the code and inserts at least one line description to each class/interface/zcml/event/GenericSetup XML/template/whatever.

Today I encountered such a challenge as there was OFS package in the core of Zope doing lots of lots of things. This package lacked README.txt or any sort of readable developer documentation. Well... that's ok, but no one actually knowns what acronym OFS means anymore. It's bad that the system runs on magic whose name no one recalls anymore... ;)

Happy weekend,

-Mikko

Alberto Lopes () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by Wouter Vanden Hove-2

I agree with 100% of what you said. I know it is not good, but from time to time I browse api.plone.org to try to learn something.

On Fri, Aug 21, 2009 at 10:06 AM, Wouter Vanden Hove <[hidden email]> wrote:

Let this this situation:
some newbie developer asks by mail a question
about ATNewsitem-schema and how it relates to ATDocument and baseContent

I am a newbie programmer, Windows user (bad, bad search tools) and have an extensive Java background.

I sent an url like this:
http://api.plone.org/Plone/3.0/public/frames/products/ATContentTypes/products.ATContentTypes.content.newsitem.ATNewsItem-class.html

This kind of information is what I usually have big trouble finding out. Sometimes I want to know something about a class or object inherited and have no idea where I should look.

I am working with Plone for 1.5 years and still have trouble finding information on classes.

question: Do C#/.NET developers need to grep in Microsoft's code to search
how they should program their application?

The problem is that since C# (like Java) is static typed, any good IDE can help you with autocompletion, doc inspection, etc.

With the great powers (given by the dynamic typing of Python) came the great responsibility (for the library developers to document much more than application programmers).

Regards,

Alberto

Dylan Jay-4 () Re: Let's turn off api.plone.org.

Reply Threaded

In reply to this post by Wouter Vanden Hove-2

On 21/08/2009, at 11:06 PM, Wouter Vanden Hove wrote:

> Dylan Jay wrote:
>
>
>> I think the closest is in Mikko/collective new developer
>> documentation
>> even though it's not published on plone.org yet.

Sorry. I didn't mean to bring up the sphinx debate again. All I meant
to say is that the introduction to that developer manual (the goal of
which is to publish on plone.org) is the perfect place to put the
reading guide that Alex suggested. The reading guide is a fantastic
idea. I think there are many fundamental concepts like object
publishing that could provide more coverage for and reading guide
would help that.

I think providing decent "written" developer documentation is the
solution like grok or lxml. I think mikko's manual is a great start at
that and the proposal to publish it into plone.org (and not some more
obscure place like api.plone.org) is a the way to go.
if there is a genuine need to use some autogenerated documetnation as
part of that process (such as roks ATCT schema doc generator) then
great but it all should be inline and searchable with all other plone
documentation.

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

1 2