ANN: New Sizzle theme, based on Guzzle

[Vinay Sajip]

I've started work on a new MIT-licensed theme. It started out as a customisation of the Guzzle theme, but I've removed some features and added some features that I found useful:

• Layout uses a small header with search box, prev/next links and index link
• Sidebar is hideable and showable with keyboard or mouse
• Entries in the TOC can be filtered by typing in what you want to match on - handy for long TOCs / larger projects
• Sidebar and content area can scroll independently (useful for larger projects)
• Typography changes - Font Awesome is integrated, slightly more condensed fonts than are used in Guzzle (e.g. Roboto rather than Open Sans)
• Support for additional Google Fonts
• Styled lists using Font Awesome icons
• Summary/detail functionality using styled lists
• A couple of custom roles, including one for Font Awesome icons
• Improved hooks for your custom JavaScript to be called on document load, etc.

You can see an example of the theme using its own documentation:

https://docs.red-dove.com/sphinx_sizzle_theme/

and for a larger project:

https://docs.red-dove.com/distlib/

I'd be grateful for any feedback about the theme and/or its documentation.

The development repository is at

https://bitbucket.org/vinay.sajip/sphinx_sizzle_theme/

and issues can also be raised there.

Regards,

Vinay Sajip

[Matthias Geier]

Thanks Vinay, this theme looks very nice!

I've used it as an example theme for my "nbsphinx" extension:

https://nbsphinx.readthedocs.io/en/sizzle-theme/

The main problem I see right now is that it doesn't really work on a
small screen (e.g. mobile phone). The original "guzzle" theme works
much better on a small screen.

For comparison, here's the same Sphinx project using the "guzzle" theme:

https://nbsphinx.readthedocs.io/en/guzzle-theme/

cheers,
Matthias

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To post to this group, send email to sphinx...@googlegroups.com.
> Visit this group at https://groups.google.com/group/sphinx-users.
> For more options, visit https://groups.google.com/d/optout.

[Vinay Sajip]

Dear Matthias,

Thanks for the feedback. Improving the responsiveness of the theme is on my todo list!

Regards,

Vinay Sajip

> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx...@googlegroups.com.

[Vinay Sajip]

Dear Matthias,

I've released version 0.0.5 of the theme, which should be better behaved on smaller screens. Do feel free to try it out.

Regards,

Vinay

On Tuesday, 16 April 2019 14:55:17 UTC+1, Matthias Geier wrote:

> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx...@googlegroups.com.

[Matthias Geier]

Thanks a lot Vinay!

I've re-built the pages: https://nbsphinx.readthedocs.io/en/sizzle-theme/

It indeed works very nicely now with small screens.

There are a few minor issues now, but I have to check if those are
actually caused by your theme or if it is my mistake. If I find
something, I'll create an issue on your issue tracker.

Thanks again for this nice theme!

cheers,
Matthias

On Thu, Apr 18, 2019 at 7:02 PM 'Vinay Sajip' via sphinx-users

> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.

[madj...@gmail.com]

I've tried it out, this theme feels awesome! thanks for your sharing!

Now I'm wondering:

1. Is there some way to adjust the top bar or even hide top bar at some point by simply using  the conf.py file, as the length of the project name or heading might increase the height of top bar too much, narrowing the visual space of the main contents.

2. How to adjust the width of sidebar?

Thanks!

[Vinay Sajip]

On Wednesday, 24 April 2019 13:16:51 UTC+1, madj...@gmail.com wrote:

1. Is there some way to adjust the top bar or even hide top bar at some point by simply using  the conf.py file, as the length of the project name or heading might increase the height of top bar too much, narrowing the visual space of the main contents.

The top bar is there so that commonly used functions (e.g. search, index) are always in view. What happens when you narrow the browser window (which would tend to make the project name or heading "too long") - post a screenshot if you spot a problem.

In general, if you want to tweak any styling decisions I've made, you should be able to do this with an overriding CSS file of your own, as described in the documentation. The problem with doing it in conf.py is that there are too many possible things that people might want to change, and conf.py wouldn't be the best place for most such tweaks.

 

2. How to adjust the width of sidebar?

No easy way other than a custom CSS  rule to override the one in sizzle.css. If you narrow the browser window (or on a small screen - tablet / phone) the sidebar is not shown by default.

If you have a public project where the theme is causing problems, point me at it and I'll try to see what's going on.

Regards,

Vinay Sajip

[madj...@gmail.com]

Hi Vinay,

Thanks for your reply. Please look at the screenshot picture below, a heading consists of multiple 'test' has the top bar occupy the most part of the screen.

How about placing vertical 'test' part horizontally below the search bar, which I think would be better to limit the top bar within a reasonable size？

[Vinay Sajip]

On Thursday, 25 April 2019 06:46:54 UTC+1, madj...@gmail.com wrote:

Thanks for your reply. Please look at the screenshot picture below, a heading consists of multiple 'test' has the top bar occupy the most part of the screen.

OK, but the search box looks a little longer than I expected: what browser is this on, and what are your browser window (inner client window) dimensions in pixels? On mine, the "Search docs ..." box is a mere 185px wide. Looks a lot bigger in your screenshot.

How about placing vertical 'test' part horizontally below the search bar, which I think would be better to limit the top bar within a reasonable size？

I'm not sure that will be the best solution, let me think about it.

Regards,

Vinay Sajip

[Vinay Sajip]

I made some CSS and HTML changes. With a long title, the top bar now looks like this:

As you can see, the vertical size of the top bar is constrained, and a tooltip has been added to allow the whole title to be seen even if part of it is cut off by the size constraint.

I'll do a bit more testing and tweaking, but this should be in the next release.

Regards,

Vinay Sajip

[madj...@gmail.com]

Great news, thanks for your efforts!

[madj...@gmail.com]

Another issue found with version 0.0.5. Suppose a TOC structure as shown below:

page1

    page1#id2

page2

    page2#id2

When I am currently on page1 and click on the 'page2#id2` entry in sidebar, the browser navigates to the topmost of page2 but not page2#id2.

Once you've been on page2, clicking 'page2#id2' entry in the sidebar works fine, the browser scrolls to the correct position.

I did some simple research and found removing the 'hidden' attribute from 'whole-page' element could get things back normal. I'm not familiar with front-end web programming, no idea why 'hidden' attribute is used here and then gets removed in a javascript section. Hope this issue could be fixed in the next release as well.

Thanks.

[Vinay Sajip]

Thanks for "kicking the tyres" on this theme! I had added the hidden class and removed it dynamically to try to improve the behaviour when JavaScript is disabled - not a critical case. I've commented it out now, and that change can also be in the next release.

Regards,

Vinay Sajip

[madj...@gmail.com]

Clicking on level 1 toc entry (URL with href="#") of the current page in sidebar does not have the page scroll to the top. Is it intentionally designed to be like this or just a bug?

[Vinay Sajip]

There have been numerous enhancements to the functionality in this area. A new release will be out soon!

[Vinay Sajip]

On Wednesday, 1 May 2019 16:13:17 UTC+1, madj...@gmail.com wrote:

Clicking on level 1 toc entry (URL with href="#") of the current page in sidebar does not have the page scroll to the top. Is it intentionally designed to be like this or just a bug?

 

I just released 0.0.7 of the theme on PyPI, which should have addressed this issue (and one or two others). If you do find issues, you can log them in the project's issue tracker at

https://bitbucket.org/vinay.sajip/sphinx_sizzle_theme/issues/new

Regards,

Vinay Sajip