New PDF builder: Sphinx-SimplePDF

76 views
Skip to first unread message

Daniel Woste

unread,
Aug 26, 2022, 4:34:13 AMAug 26
to sphinx-users
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

unread,
Aug 26, 2022, 5:40:01 AMAug 26
to sphinx...@googlegroups.com
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

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

unread,
Aug 26, 2022, 6:54:50 AMAug 26
to sphinx...@googlegroups.com
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

unread,
Aug 26, 2022, 6:57:31 AMAug 26
to sphinx...@googlegroups.com
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.
Message has been deleted

bradley...@gmail.com

unread,
Aug 27, 2022, 9:59:20 AMAug 27
to sphinx-users
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

unread,
Aug 29, 2022, 2:03:27 AMAug 29
to sphinx...@googlegroups.com
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. 

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.

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

unread,
Aug 29, 2022, 3:57:55 PMAug 29
to sphinx-users
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

unread,
Aug 30, 2022, 11:53:59 AMAug 30
to sphinx-users
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!
Reply all
Reply to author
Forward
0 new messages