search broken in community docs and official docs

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

search broken in community docs and official docs

Jan-Wijbrand Kolman-3
Hi,

The search function is broken in the "community" and "official"
documentation trees.

I think this is because both override the "layout.html", that sphinx
otherwise would have generated. This layout.html references several
javascript- and other resources, that are different or no longer
available in the builds by the current Sphinx version.

Questions:

* Do we really really want a layout for the documentation builds to be
so different from a normal sphinx build, to require a layout.html
override (that then needs careful maintenance)? Or should we lower the
ambitions a little here?

* Who created these layouts, and might be able to help me getting things
straightened out again?

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: search broken in community docs and official docs

Uli Fouquet
Hi,

Jan-Wijbrand Kolman wrote:
> Hi,
>
> The search function is broken in the "community" and "official"
> documentation trees.
>
> I think this is because both override the "layout.html", that sphinx
> otherwise would have generated. This layout.html references several
> javascript- and other resources, that are different or no longer
> available in the builds by the current Sphinx version.

That's right.

> Questions:
>
> * Do we really really want a layout for the documentation builds to be
> so different from a normal sphinx build, to require a layout.html
> override (that then needs careful maintenance)? Or should we lower the
> ambitions a little here?

The layout.html doesn't has to be that large. I like the special 'Grok
layout', so I'd like to keep it. I could, however, imagine two changes:

- The official grok docs and the community docs now have exactly the
  same layout. That might be confusing. Maybe one could could give one
  of the layouts a darker or brighter touch so that you can see from
  the colors immediately whether you're watching community docs or the
  reference.

- We could build a 'Grok theme' for Sphinx.

> * Who created these layouts, and might be able to help me getting things
> straightened out again?

I guess I am to blame for the layout.html. However, that files were
created a few years ago when Sphinx was in the very beginnings and
'inheriting templates' was not possible that easily.

Anyway, I modified the layout.htmls for both, the community docs and the
reference docs. Both are now shorter and hopefully better to understand
and maintain. Also searching should work again now.

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: search broken in community docs and official docs

Jan-Wijbrand Kolman-3
On 1/11/11 9:07 AM, Uli Fouquet wrote:

>> * Do we really really want a layout for the documentation builds to be
>> so different from a normal sphinx build, to require a layout.html
>> override (that then needs careful maintenance)? Or should we lower the
>> ambitions a little here?
>
> The layout.html doesn't has to be that large. I like the special 'Grok
> layout', so I'd like to keep it. I could, however, imagine two changes:
>
> - The official grok docs and the community docs now have exactly the
>    same layout. That might be confusing. Maybe one could could give one
>    of the layouts a darker or brighter touch so that you can see from
>    the colors immediately whether you're watching community docs or the
>    reference.

Sounds like a good plan, to have slightly different coloring or
something for the community docs versus the official docs.

> - We could build a 'Grok theme' for Sphinx.

I'm not (yet) well versed in Sphinx: what would a Grok Theme brings us?

> Anyway, I modified the layout.htmls for both, the community docs and the
> reference docs. Both are now shorter and hopefully better to understand
> and maintain. Also searching should work again now.

Great! They should be online now... well there aren't... but that's
because I made a mistake in the cronjobs: the PATH setting was not
correct. I'll fix that. Thanks!

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: search broken in community docs and official docs

Uli Fouquet
Jan-Wijbrand Kolman wrote:
> On 1/11/11 9:07 AM, Uli Fouquet wrote:

[snip]

> Sounds like a good plan, to have slightly different coloring or
> something for the community docs versus the official docs.

Then all we'd need is a volunteer a bit fluent in webdesign. Someone
around? Sebastian? We'd need a slightly different layout (most probably
colors) which would come down to minor CSS changes, I guess.

> > - We could build a 'Grok theme' for Sphinx.
>
> I'm not (yet) well versed in Sphinx: what would a Grok Theme brings us?

I haven't done that myself yet ;) But from the Sphinx docs I get the
impression that we could share one theme for both, the community and the
reference docs and set differences in the respective conf.py files.

Right now, both layout.htmls differ slightly, for instance for the upper
link bar. With a theme we might could turn these differences into
conf.py-settable options and wouldn't have to care for two nearly
identical layout.htmls in two different locations any more.

The only question would be how to share the theme (basically a ZIP file
or a subdir) in the different repository types. Would mercurial support
something similar to svn:external (which is ugly, I know)? Or vice
versa? I am a complete Mercurial-illiterate ;)

> > Anyway, I modified the layout.htmls for both, the community docs and the
> > reference docs. Both are now shorter and hopefully better to understand
> > and maintain. Also searching should work again now.
>
> Great! They should be online now... well there aren't... but that's
> because I made a mistake in the cronjobs: the PATH setting was not
> correct. I'll fix that. Thanks!

Seems it works fine now :) Thanks a lot!

Best regards,

--
Uli


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

signature.asc (196 bytes) Download Attachment