SimplePDF customization

[kreuzberger]

Current configuration

Currently the customization is done via entries in the conf.py file. These include variables from html_context and simplepdf_vars as i know. The intention seems to be to add html_context variables for "content" that should be visible in the html and simplepdf_vars configures values (e.g. like colors, background) for the css/scss files.

Some content is not part of the html view, this content is only available e.g. on print. These includes e.g. the "counter(page)" visible in the pdf top-left output. Also the top-right content is "hard-coded" into "string(heading)". This is currently done in the "scss" files and cannot be configured by the user.

Motivation

The user wants to customize the pdf output to have a header/footer section in his pdf. The content should be definable by the user and use the provided theme

What should the user be able to configure

The user should be able to configure the header/footer content for the template with elements from html or variables from scss context. This should include all "design" independent @pages sections.

These are: "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right"

"top-left" is currently not good to configure by the template, cause it has a fixed width to contain the page number.

The user now wants to add content to the bottom on each pdf page that includes e.g.

• page/totalnumber of pages, e.g. in the bottom-left
• copyright information, e.g. in the bottom-center
• Dokument output name (e.g. mydoc.pdf), e.g in the bottom right

This content should be definable via "simplepdf_vars" cause they do not normaly appear in the html output. If they appear, they should also be usable.

Possible solution

conf.py:

simplepdf_vars = {
  'bottom-center-content' : 'pageElement(back-cover-footer)',
  'top-left-content' : 'counter(page)',
  'top-center-content' : 'string("Only visible in page print")',
  'top-right-content' : 'string(heading)'
}

_page.scss:

@page {
  @top-right {
    content: $top-right-content;
    font-size: 9pt;
    height: 1cm;
    vertical-align: middle;
    width: 100%;
  }
}

The values e.g. from pageElement are defined in html_context and maybe used e.g. in cover.html or back-cover.html. (E.g. reuse of the copyright information) But if they only are intended to be used in "print" output, the should be defined as text in simplepdf_vars

Open Questions

• Which variables should be part of the basic theme / layout and what is just intend to be customized by a private/local css. All currently mentioned changes could e.g. be overwritten in a custom css with the @page section
• What needs to be changed/adapted in the basic theme/layout
• How to add custom themes for sphinx-simplepdf

[kreuzberger]

This is intended as an proposal to possible customization, started during the bugfix of #4.

[danwos]

Thanks for starting this discussion. Indeed there is no real concept right now on what and how things shall be configured.

For the scss/css configuration, I would always create an internal var inside _variables.scss first:

$primary: config('primary', '#961a1a') !default;
$top-right-content: config('top-right-content', 'The default content if not specified by user') !default;

This allows us (the devs) to set defaults at one single location.

As for the rest, I'm mostly fine. Only missing thing is the usage of the sphinx _templates folder.

It allows overwriting the html-template with project-specific template-files. So for me, this is the mechanism to use, if I want to add more complex data and not just a single string for the headline. But our templates are just very focused and don't tell the author what else can be used (no sections, which are commented out). And I haven't tested it yet.

For custom themes, there could be a simplepdf-variable simplepdf-theme, which takes the name of the theme to use when make simplepdf gets called. Currently this value is hard-coded. But for sure, this theme needs to be installed as its own sphinx-theme. But forking this repo could be a good starting point :)

[kreuzberger]

Still forked :smile: Ok, then i would start with the variables to configure the page top-right-content and top-center-content. default would be like the current: top-right is the heading and top center would be an empty string. the variable will be added to _variables.scss

[danwos]

I close this issue, as the first implementation got already merged. Thanks for it :+1:

[kreuzberger]

But our templates are just very focused and don't tell the author what else can be used (no sections, which are commented out).

Short question: The section numbers do not appear in the html generated by the SimplePDFBuilder, independent of the use template. You stated that "sections" are commented out. What does this mean? My TOC contains section numbers, but in the generated html they are not shown.

[danwos]

Sphinx-SimplePDF starts a SinglePageHtmlBuild, which is a builder from Sphinx. This creates a single HTML file and removes all toctree entries, as otherwise you would have a page-toctree per chapter, as you use toctree normally inside each index-rst-file.

So a toctree is only added at the end of the singlepage HTML, as sidebar-entry. So the config from a toctree is not taken for the sidebar-toctree. (It took me half a day to figure out how this mechanism is working).

However, if :numbered: is used, the sections-names should get a chapter-number as a prefix. And these numbers can then also be seen in the final PDF (incl. the toctree there). But the sidebar-toctree does not take this into account (as far as I know).

The DEMO-PDf is also using numbered chapters, but our documentation PDF is not. Maybe two good examples, if you want to play around :)

[kreuzberger]

Ok, my index.rst uses toctree :numbered: The generated html has a numbered toc after the cover page, but the entries in the html have not. I attached the pdf from the demo as example. The toc is numbered, the sections in the pdf are not. I am using Sphinx 4.5.0. Maybe this is the issue.

Sphinx-SimplePDF-DEMO.pdf

[kreuzberger]

This is part of the generated html. The toctree contains the numbers, but the sections itself do not. Normally the have an extra span part lkie this: <h3><span class="section-number">2.2. </span>

` ```

10.22. Example Submenu 2

   </ul>
  </li>
  <li class="toctree-l1">
   <a class="reference internal" href="#document-images">
    11. Images
   </a>
   <ul>
    <li class="toctree-l2">
     <a class="reference internal" href="#svg">
      11.1. SVG
     </a>
    </li>
    <li class="toctree-l2">
     <a class="reference internal" href="#jpg">
      11.2. JPG
     </a>
    </li>
   </ul>
  </li>
 </ul>
</div>

[kreuzberger]

Tell me if i should start this discussion in an new issue

[danwos]

You are right. I also just noticed that the numbers are missing in front of the section names.

I have currently no idea what the cause of this problem is. Can you create a new bug report for it? Thanks.