Closed kreuzberger closed 1 year ago
This is intended as an proposal to possible customization, started during the bugfix of #4.
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 :)
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
I close this issue, as the first implementation got already merged. Thanks for it :+1:
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.
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 :)
Ok, my index.rst uses toctree :numbered:
The generated html has a numbered toc after the cover page, but the
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>
` ```
</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>
Tell me if i should start this discussion in an new issue
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.
Current configuration
Currently the customization is done via entries in the conf.py file. These include variables from
html_context
andsimplepdf_vars
as i know. The intention seems to be to add html_context variables for "content" that should be visible in the html andsimplepdf_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.
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:
_page.scss:
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 insimplepdf_vars
Open Questions