New PDF builder: Sphinx-SimplePDF

[Daniel Woste]

Hi all,

just wanted to let you know that a new PDF builder is available, which hopefully makes some stuff easier regarding PDF generation: Sphinx-SimplePDF.

Docs HTML : https://sphinx-simplepdf.readthedocs.io/

Only 2 commands are needed to get a PDF out of your existing docs:
1) pip install sphinx-simplepdf
2) make simplepdf

Sphinx-SimplePDF provides already a nice-looking, modern theme (incl. front and back cover).  See following link as example.

Docs PDF: https://sphinx-simplepdf.readthedocs.io/en/latest/_static/Sphinx-SimplePDF.pdf

Theming is done via HTML and CSS, so no Latex is involved.
(Backend is based on weasyprint)
As it is based on HTML, all extensions should be supported out of the box.

Main colors and images can be configured inside your conf.py file.

So no CSS knowledge is needed for generic changes.

I hope you like it and that it is useful for your project.
Happy to get some feedback :)

Have a great day,
  Daniel

[Renato Pontefice]

Hi all,

I’ve typed the command tp install simplepdf and the make simplepdf.

This is the result:

make simplepdf

Sto eseguendo Sphinx v5.1.1

sto creando la cartella di output... fatto

loading pickled environment... fatto

Setting theme to sphinx_simplepdf

Generating css files from scss-templates

building [mo]: targets for 0 po files that are out of date

building [simplepdf]: all documents

updating environment: 0 added, 0 changed, 0 removed

looking for now-outdated files... none found

preparing documents... fatto

assembling single document... fatto

writing... fatto

writing additional files... fatto

copying static files... fatto

copying extra files... fatto

dumping object inventory... fatto

Traceback (most recent call last):

  File "/usr/local/bin/weasyprint", line 5, in <module>

    from weasyprint.__main__ import main

  File "/usr/local/lib/python3.10/site-packages/weasyprint/__init__.py", line 336, in <module>

    from .css import preprocess_stylesheet  # noqa isort:skip

  File "/usr/local/lib/python3.10/site-packages/weasyprint/css/__init__.py", line 25, in <module>

    from . import computed_values, counters, media_queries

  File "/usr/local/lib/python3.10/site-packages/weasyprint/css/computed_values.py", line 9, in <module>

    from ..text.ffi import ffi, pango, units_to_double

  File "/usr/local/lib/python3.10/site-packages/weasyprint/text/ffi.py", line 401, in <module>

    pango = _dlopen(

  File "/usr/local/lib/python3.10/site-packages/weasyprint/text/ffi.py", line 385, in _dlopen

    return ffi.dlopen(names[0])  # pragma: no cover

  File "/usr/local/lib/python3.10/site-packages/cffi/api.py", line 150, in dlopen

    lib, function_cache = _make_ffi_library(self, name, flags)

  File "/usr/local/lib/python3.10/site-packages/cffi/api.py", line 832, in _make_ffi_library

    backendlib = _load_backend_lib(backend, libname, flags)

  File "/usr/local/lib/python3.10/site-packages/cffi/api.py", line 827, in _load_backend_lib

    raise OSError(msg)

OSError: cannot load library 'pango-1.0-0': dlopen(pango-1.0-0, 0x0002): tried: '/usr/local/lib/pango-1.0-0' (no such file), 'pango-1.0-0' (no such file), '/usr/local/lib/pango-1.0-0' (no such file), '/usr/lib/pango-1.0-0' (no such file), '/Users/renatopontefice/sphinx/docs/pango-1.0-0' (no such file).  Additionally, ctypes.util.find_library() did not manage to locate a library called 'pango-1.0-0'

build succeeded.

The HTML page is in build/simplepdf.

But (as the log show) in simplepdf folder I found just an index.html and objects.inv

No .pdf file

• Looks like the installation did not go well

Can you help me? I’me not aware of python.

Thank you

Renato

--
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 view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/e106d88e-4fb6-4891-8ec9-ecf7ea36f605n%40googlegroups.com.

[Daniel Woste]

Hi Renato,

thanks for the fast feedback.

This looks like a bug, so I created a bug issue: https://github.com/useblocks/sphinx-simplepdf/issues/6

As I have currently no idea for a solution, I only have one question: What operating system are you using?

I will try to solve this in the next days.

Thanks for testing it!

  Daniel

[Renato Pontefice]

Mac osx 12.5.1

Let me know.

Thank you

Renato

--
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 view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/257e2d0d6ecfd7c9034bd2f5a6959c819538d70f.camel%40useblocks.com.

[bradley...@gmail.com]

Looks very nice, but it seems to display the latex input instead of rending the equations (as intended by latex) ?

Sorry if you got two copies of this post, I was trying to fix a typo in the previous version.

[Daniel Woste]

Ohh yes, grid design for HTML output is tough to be transformed correctly for PDF output.
There are currently two ways to solve it.

1) Some custom CSS via a custom.css file. 

https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html

2) Using the "if-builder" directive.

This one is available since Sphinx-SimplePDF 1.3 and it allows you to decide what content shall be used for which builder.

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

So you could decide to simply remove the image inside the grids for PDF build.
Or you can add some rst, which is not based in sphinx-design.

2) is the easiest one, but would force you to maintain problematic content twice.

1) is the cleanest one, but can be very specific to the current documentation.

I'm sure Sphinx-SimplePDF will get some extensions specific CSS code, to avoid such general show-stoppers in future.

But it would be really helpful and welcome,   if everybody who figures out some custom css rules could share thes with Sphinx-SimplePDF via a PR.

Cheers,

 Daniel

On Sun, 2022-08-28 at 05:02 +0300, Luc Saffre wrote:

Thanks, Daniel, for having written this cool builder. 
I tried it on one of my websites, and it gave a nice result quasi out of the box. 
That's a convincing start!

Of course the devil is in the detail. A show-stopper for me is that I use sphinx-design when i want text or images either side-by-side (on a larger screen) or top-down (on a small screen). 

Example::

.. grid:: 1 2 2 2

  .. grid-item::

    This goes to the left column when there is enough space.

  .. grid-item::

    This goes to the right column when there is enough space.


These parts of my website aren't rendered correctly in the pdf version. 

Luc

[aero engineer]

I tried it.  It does produce a pdf with a nice look.  But the .png images which are 810 pixels wide are running off the right side of the pdf pages.  Is there a fix for this?  Thanks.

[Marvin Kastner]

Thank you very much for this nice builder! I have tried it out and created some issues at the GitHub project. I am really looking forward to using it! I like your choice of styles etc.! Also thanks for sharing your code!