community documentation deployed on grok.zope.org

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

community documentation deployed on grok.zope.org

Jan-Wijbrand Kolman-3
Hi,

With considerable latency, lo and behold: the community documentation is
being deployed on grok.zope.org:

   http://grok.zope.org/doc/community/

It is updated hourly.

A couple of remarks from my perspective:

* Somehow the "generated on"-timestamp is missing from the index page.
   I think it should be there, but I do not know why it isn't.

* The index page suggests this documentation is for the Grok-1.2
   release. I'm not sure we can claim that for each document. Maybe we
   should label each document with a target version.

* We might want to define a document template for the documentation,
   including the aforementioned target version, author information, etc.

* There's a navigation menu at the top in the form of several tabs. The
   links in there are not correct, but I actually wonder whether we
   should keep the links there in the first place.

* I removed the latex and PDF rendering parts from the build script.
   They didn't seem to work at this moment. At least not on the
   grok.zope.org host.

regards, jw

_______________________________________________
Grok-dev mailing list
[hidden email]
https://mail.zope.org/mailman/listinfo/grok-dev
Reply | Threaded
Open this post in threaded view
|

Re: community documentation deployed on grok.zope.org

Uli Fouquet
Hi JW,

Jan-Wijbrand Kolman wrote:

> With considerable latency, lo and behold: the community documentation is
> being deployed on grok.zope.org:
>
>    http://grok.zope.org/doc/community/

Great! Thanks a lot to all who helped yet!

> It is updated hourly.
>
> A couple of remarks from my perspective:
>
> * Somehow the "generated on"-timestamp is missing from the index page.
>    I think it should be there, but I do not know why it isn't.

That's really mysterious. The layout at least should insert the
`last_updated` value. I currently have no clue.

> * The index page suggests this documentation is for the Grok-1.2
>    release. I'm not sure we can claim that for each document. Maybe we
>    should label each document with a target version.

Strictly speaking, the documentation might have a version of its own,
but having that displayed could be very confusing for readers.

> * We might want to define a document template for the documentation,
>    including the aforementioned target version, author information, etc.

One could simply add markup like this on every page::

  :Author: JW <[hidden email]>
  :Version: This tutorial is tested for Grok versions 1.0-1.2

I guess this is easier to handle and maintain than complicated template
magic.

> * There's a navigation menu at the top in the form of several tabs. The
>    links in there are not correct, but I actually wonder whether we
>    should keep the links there in the first place.

IMO all links except the last two ones ("What's changed" and "Grok
Community Documentation") should stay. One can discuss, however, whether
the tutorial and developer notes should be shipped with the reference
rather than with the the community docs.

> * I removed the latex and PDF rendering parts from the build script.
>    They didn't seem to work at this moment. At least not on the
>    grok.zope.org host.

Can you tell what went wrong? Most people with a more recent LaTeX
install should be able to build PDFs. At least it works here.

Thanks for all your efforts!

Best regards,

--
Uli


_______________________________________________
Grok-dev mailing list
[hidden email]
https://mail.zope.org/mailman/listinfo/grok-dev

signature.asc (196 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: community documentation deployed on grok.zope.org

Jan-Wijbrand Kolman-3
On 1/10/11 15:42 PM, Uli Fouquet wrote:
>> * Somehow the "generated on"-timestamp is missing from the index page.
>>     I think it should be there, but I do not know why it isn't.
>
> That's really mysterious. The layout at least should insert the
> `last_updated` value. I currently have no clue.

Maybe I'm doing something wrong here? Can someone reproduce not getting
an updated timestamp?

>> * We might want to define a document template for the documentation,
>>     including the aforementioned target version, author information, etc.
>
> One could simply add markup like this on every page::
>
>    :Author: JW<[hidden email]>
>    :Version: This tutorial is tested for Grok versions 1.0-1.2
>
> I guess this is easier to handle and maintain than complicated template
> magic.

Oh, sure, that's what I meant: a template that people can copy to start
a new document with.

>> * There's a navigation menu at the top in the form of several tabs. The
>>     links in there are not correct, but I actually wonder whether we
>>     should keep the links there in the first place.
>
> IMO all links except the last two ones ("What's changed" and "Grok
> Community Documentation") should stay. One can discuss, however, whether
> the tutorial and developer notes should be shipped with the reference
> rather than with the the community docs.

I think these navigational links do belong in the
official-documentation-tree, that indeed contain the tutorial etc.
Actually, now I notice the little title above the tab bar says "Official
Grok Documentation", where I guess it should say "Grok Community
Documentation", right?

>> * I removed the latex and PDF rendering parts from the build script.
>>     They didn't seem to work at this moment. At least not on the
>>     grok.zope.org host.
>
> Can you tell what went wrong? Most people with a more recent LaTeX
> install should be able to build PDFs. At least it works here.

Hmmm, for the grok-doc checkout, the build script tries to call "make
all_pdf", a target that seems not to be defined in the Makefile. Again,
I might be doing something wrong here.

regards, jw

_______________________________________________
Grok-dev mailing list
[hidden email]
https://mail.zope.org/mailman/listinfo/grok-dev
Reply | Threaded
Open this post in threaded view
|

Re: community documentation deployed on grok.zope.org

Uli Fouquet
Jan-Wijbrand Kolman wrote:
> On 1/10/11 15:42 PM, Uli Fouquet wrote:
> >> * Somehow the "generated on"-timestamp is missing from the index page.
> >>     I think it should be there, but I do not know why it isn't.
> >
> > That's really mysterious. The layout at least should insert the
> > `last_updated` value. I currently have no clue.
>
> Maybe I'm doing something wrong here? Can someone reproduce not getting
> an updated timestamp?

I don't get the timestamp neither.

[snip: template]

> >> * There's a navigation menu at the top in the form of several tabs. The
> >>     links in there are not correct, but I actually wonder whether we
> >>     should keep the links there in the first place.
> >
> > IMO all links except the last two ones ("What's changed" and "Grok
> > Community Documentation") should stay. One can discuss, however, whether
> > the tutorial and developer notes should be shipped with the reference
> > rather than with the the community docs.
>
> I think these navigational links do belong in the
> official-documentation-tree, that indeed contain the tutorial etc.
> Actually, now I notice the little title above the tab bar says "Official
> Grok Documentation", where I guess it should say "Grok Community
> Documentation", right?
I think so too and tried to change that in the docs.

> >> * I removed the latex and PDF rendering parts from the build script.
> >>     They didn't seem to work at this moment. At least not on the
> >>     grok.zope.org host.
> >
> > Can you tell what went wrong? Most people with a more recent LaTeX
> > install should be able to build PDFs. At least it works here.
>
> Hmmm, for the grok-doc checkout, the build script tries to call "make
> all_pdf", a target that seems not to be defined in the Makefile. Again,
> I might be doing something wrong here.
Usually there are two Makefiles. One (the 'usual one') to run `make
latex` which in turn generates a new Makefile in the build/latex/ subdir
which accepts `make all-pdf`. But I didn't look into the builder script
yet.

Best regards,

--
Uli


_______________________________________________
Grok-dev mailing list
[hidden email]
https://mail.zope.org/mailman/listinfo/grok-dev

signature.asc (196 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: community documentation deployed on grok.zope.org

Vincent Fretin
On Mon, Jan 10, 2011 at 4:49 PM, Uli Fouquet <[hidden email]> wrote:
Usually there are two Makefiles. One (the 'usual one') to run `make
latex` which in turn generates a new Makefile in the build/latex/ subdir
which accepts `make all-pdf`. But I didn't look into the builder script
yet.
That's right.

For latex, your normally need texlive on a recent OS, or
tetex-base tetex-bin tetex-extra on an old one.

Vincent

_______________________________________________
Grok-dev mailing list
[hidden email]
https://mail.zope.org/mailman/listinfo/grok-dev