Custom Theme Support

[kreuzberger]

As discussed earlier in #19, the simplepdf customisation should/could be done with a normal sphinx theme. This should be provided via a new config value: simplepdf_html_theme. I want to clearify (for myself) in this issue the main concept for this.

1) Should or could these themes inherit from simplepdf_theme This would have the advantage to use main.css wich is generated during build. 2) In simplepdf.py there are some hardcoded theme handling entries:

 self.app.config.html_sidebars = {'**': ["localtoc.html"]}
 self.app.config.html_theme_options = {}  # Sphinx would write warnings, if given options are unsupported.

What has to be adapted here and should there an extra simplepdf_html_theme_options?

Use Case

I want a pdf used as online help for my application generated with simplepdf. Due to the use as online help this pdf should have

• no cover
• no back_cover
• configurable toc/noctoc (depending on the "length" of the help) -> sidebar or not

Questions

Should this be done in an own theme or should the simplepdf_theme made configurable (html_theme_options) e.g. nosidebar -> no toc nocover -> no cover page or no cover/backcover nobackcover -> no back cover page, see above

If a custom theme should be used this must be added in simplepdf.py for theme selection.

[danwos]

Good questions. I think making our theme configurable is never enough for some use cases. There will be always a case, where different stuff is needed.

So I think we should concentrate on the "other theme" solution first, as this should make every wish possible.

And your thoughts about reusing the simplepdf-theme and only provides needed changes for your own themeing, are correct. There should not be the need to construct a complete theme from scratch and copy&paste needed css-data.

I also hope that it is enough to put theme-templates in the _templates folder only, so the user does not need to define an entirely new theme.

technical realization

New conf.py option: simplepdf_theme, which takes the name of a theme. The default is sphinx-simplepdf. Also simplepdf_theme_options and simplepdf_sidebars should be configurable.

Open questions

• How can _templates be used, to extend our theme?

[kreuzberger]

Hm. ok, i tried it the hard way this morning and learned how to create own theme and make a wheel out of it. Technically i had to adapt layout.html and everything was fine. In my theme.conf i "derived" from simplepd_theme and disabled the sidebars.

In simplepdf_builder i adapted the variable for the theme and in _toctree_fix handled the "Nonexistence" of the sidebar.

Main problem ist the @page :first entry (from _pages.scss). In no cover cases this should be "off". If this would be a theme option, it can be configured out in cases of "nocover". So what should be configured in the theme (assuming ALL basic configure options could be used)

so what should be in options (e.g all basic options should be supported) and what should bei in simplepdf_sidebars?

Suggestions: simplepdf_options: 'nocoverpages' = bool, Default true

Should toc/notoc be handled via "nosidebar" or should this be a separate option.

What are the default values inf simplepdf_sidebars? I assume the self.app.config.html_sidebars = {'**': ["localtoc.html"]}