add theme option 'pdf_url'

[umarcor]

The purpose of this PR is to discuss about adding a pdf_url option to the theme, to be linked as an icon in the header (or footer) of the theme.

Since Sphinx supports building multiple formats (html, pdf, epub, man, etc.), it is common to build HTML and PDF versions at least. It is also common to link the PDF from the HTML. Actually, on RTD, their custom overlay does provide such link.

This PR adds theme option pdf_url, for users to provide the relative or absolute path to the PDF that matches an HTML build.

I would like feedback about the modifications to src/partials/header.html. On the one hand, I wonder if there are better classes for this button/icon. On the other hand, modifying the content of src is unwanted, according to https://github.com/jbms/sphinx-immaterial/blob/main/CONTRIBUTING.md#unwanted-changes. Hence, is there any alternative which does not imply doing so?

[2bndy5]

Thank you for reading the CONTRIBUTING.md; so few seem to bother. Any changes to the HTML templates should be proposed upstream to mkdocs-material theme because we try not to deviate from the templates we inherit from there.

TBH, I think you can easily add this icon (to the footer) using the html_theme_options["social"] option.

html_theme_options = {
    "social": [
        {
            "icon": "fontawesome/solid/file-pdf",
            "link": "path/to/pdf",
            "name": "Download the PDF",  # the tooltip for the icon
        },
    ],
}

---

Sphinx supports building multiple formats (html, pdf, epub, man, etc.)

To be clear, Sphinx does not natively support PDF creation. Instead, RTD uses Sphinx's Latex builder and then feeds the Latex output through third party software (which is mostly specific to Linux) to generate a PDF.

I'm curious if you've successfully built a PDF with sphinx using this theme. At the moment, we officially support HTML builders. We do build our docs in CI with Sphinx' Latex builder to make sure contributions don't break it, but Latex support is not a development goal (currently).

Last time I tried to make a PDF with this theme (using RTD's optional feature), there were numerous "unknown references" in the Sphinx build log. Also, the Table of Contents (if toctree directives do not precede any content in index.rst) was appended to the previous section with a header.

[2bndy5]

A link could also be put in the global ToC:

.. toctree::

   Download the PDF <https://path/to/pdf>

The path can be relative too, but Sphinx will complain if the path does not exist at build time. Additionally, this will also show in the navigation tabs (when navigation.tabs feature is enabled).

[mgielda]

Hi @2bndy5! Thanks for the speedy reply. The Sphinx PDF generation capability, even if it uses LaTeX (which we also do), it is kind of central and many projects seem to use it, it's in no way connected to RTD as far as I can say. The reason RTD has it is that Sphinx had it, not the other way around, I think.

There seems to be a new PDF generator in Sphinx we also want to try, and in general, MD (so also MyST) lends itself better to PDF generation potentially. So I don't think we can forgo that.

While the footer/social media hack is interesting, it's a rather invisible place and putting it next to GH and twitter icons seems confusing. I'd rather not use that solution.

I think we could potentially try to upstream it to the mkdocs theme at some point. I would actually consider the ability to do a custom icon/link in the top bar a nice addition. It would not have to be specific to PDF really, come to think of it.

[2bndy5]

The Sphinx PDF generation capability, even if if uses LaTeX (which we also do) is kind of central and many projects seem to use it, it's in no way connected to RTD as far as I can say. The reason RTD has it is that Sphinx had it, not the other way around, I think.

Please check your RTD project's build logs. You will see RTD build Latex output and feed it into third party software (installed on RTD's docker image) to generate the EPUB/PDF files. Sphinx is not capable of generating PDF by itself (see the available builders that ship with Sphinx). There are numerous alternatives to get sphinx to generate a PDF directly (I've used rst2pdf in the past), all of which incorporate a custom Sphinx builder. You could look into rhinotype as a practical example.

If you're generating PDFs locally without RTD build artifacts, then I'd be interested in how you're doing it.

There seems to be a new PDF generator in Sphinx we also want to try

More info please. IDK what you're referring to.

---

I think we could potentially try to upstream it to the mkdocs theme at some point. I would actually consider the ability to do a custom icon/link in the top bar a nice addition. It would not have to be specific to PDF really, come to think of it.

Agreed, but I have no say in that decision. To be clear, I'm not willing to accept this PR without getting feedback on a proposal upstream first. Beware, I'll probably err towards the upstream proposal's reaction. If it turns out that upstream already has an option for PDF download links, then I'm open to porting the functionality here (if not done already).

After some thought, I think the proposal to upstream could be a new block in partials/header.html named extraheader. This way users can add whatever they want by extending the theme via template overrides (similar to how the announce block is implemented).

Upon reading the proposed pdf_url option, I initially thought that a new icon would be generated next to the "edit this page" icon (edit_uri option)

Remember though that the header is currently designed to use a plethora of other features like

• version selection
• language selections (which we haven't officially supported yet)
• repo representation
• search
• theme palette toggling
• page title
• hamburger menu button

Amidst all these features, I'm not sure if upstream will be open to adding more to the header... That's why I'm trying to suggest alternatives.

I think you could also add a hero to every page (customized with extra CSS) by using the rst_prolog option in conf.py (MyST doesn't seem to have an equivalent to rst_prolog though).

[jbms]

Adding a new block to the header would be simplest and most general, and probably a good idea regardless of whether another more specific option is added. The tricky thing is that there are multiple possible places, so possibly more than one block is needed.

[mgielda]

Thanks for the feedback here - note that we are absolutely not in a hurry to reach a conclusion or get this PR merged, so we're happy to chat until we find the best solution, thanks for the suggestions. I would lean towards finding a way to add a new block to the header as a general solution, to help not just our but potentially other use cases. Hopefully the upstream theme likes that idea, but let's kick it around before we actually go and suggest it.

The new PDF builder is SimplePDF:

https://groups.google.com/g/sphinx-users/c/r4ahhcagNK0/m/dqlBZjFKAgAJ

https://sphinx-simplepdf.readthedocs.io/en/latest/

As far as I have seen, it produces some pretty nice PDFs but I would need to battle test it against some of the more complex documentations we have.

As far as memory serves me, the "main" PDF build target, latexpdf, is a first-class Sphinx target since at least 2010 (when I first used it for one of the first projects our company did), before RTD days. It has some OS dependencies, indeed takes multiple passes, and probably only works well on Linux (never tried it on any other OS to be honest) but it's a first-class citizen nonetheless, if somewhat less often used than the HTML one. The PDFs it makes are kinda dated but pretty robust and have served us well for like 12 years now :)

We also use rst2pdf for other things but we are phasing it out. I hope SimplePDF can be a good replacement of all this.

But that is kind of an off-topic really - we will come back with some idea on how we would implement the new header block (both here and upstream I guess).

[2bndy5]

It would still be a good idea to involve squidfunk in this discussion. So, I suggest opening a discussion upstream. We can work with whatever is decided from there.