ci: generate pdf

[numero-744]

PDF generation is done in two phases: rst->tex & tex->pdf. I get an error in the first phase.

Expected: create latex files

Actual:

% make latex
Extension error:
convert exited with error:
[stderr]
b"convert-im6.q16: delegate failed `'rsvg-convert' -o '%o' '%i'' @ error/delegate.c/InvokeDelegate/1966.\nconvert-im6.q16: unable to open file `/tmp/magick-js2pMmJNdpHh0gLO_sYh6hvy9N2dsNJn': No such file or directory @ error/constitute.c/ReadImage/614.\nconvert-im6.q16: no images defined `/docs/docs/doctrees/images/process_rtl.png' @ error/convert.c/ConvertImageCommand/3229.\n"
[stdout]
b''
make: *** [Makefile:19: latex] Error 2

[Readon]

How about add the compiling PDF task to CI, so that it can be easily released without worry about the compilation environment.

[Readon]

According to the message you give, it seems that some files and directory is missing, which is not met from my environment.

[numero-744]

How about add the compiling PDF task to CI, so that it can be easily released without worry about the compilation environment.

This was my next plan 😉 I am first trying to get it locally in a docker image to fix this kind of issues. (Using Dockerfile in master branch)

which is not met from my environment

Good thing! Now I have to understand why it fails…

[Readon]

What version of Sphinx are you using? Mine is v4.1.2, which works.

[numero-744]

v5.2.0

[numero-744]

With 4.1.2 I get the Python 3.10 errors

[Readon]

That might be caused by some dependent library.

[Readon]

Have you tried to compile the docs directly by

sphinx-build -M latexpdf "source" "docs"

[numero-744]

Same result

[Readon]

I think the log would show you some clue.

…

---Original--- From: ***@***.***> Date: Tue, Oct 25, 2022 00:00 AM To: ***@***.***>; Cc: ***@***.******@***.***>; Subject: Re: [SpinalHDL/SpinalDoc-RTD] Error trying to generate pdf (Issue#132) Same result — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you commented.Message ID: ***@***.***>

[wifasoi]

Works on my end.. with sphinx 5.2 and this is the pip freeze:

alabaster==0.7.12
Babel==2.10.3
cairocffi==1.4.0
CairoSVG==2.5.2
certifi==2022.9.24
cffi==1.15.1
charset-normalizer==2.1.1
cssselect2==0.7.0
defusedxml==0.7.1
docutils==0.16
idna==3.4
imagesize==1.4.1
Jinja2==3.1.2
MarkupSafe==2.1.1
packaging==21.3
Pillow==9.2.0
pycparser==2.21
Pygments==2.13.0
pyparsing==3.0.9
pytz==2022.4
PyYAML==6.0
requests==2.28.1
six==1.16.0
snowballstemmer==2.2.0
Sphinx==5.2.0
sphinx-multiversion==0.2.4
sphinx-rtd-theme==0.5.2
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==2.0.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.5
sphinxcontrib-wavedrom==3.0.2
svgwrite==1.4.3
tinycss2==1.1.1
urllib3==1.26.12
wavedrom==2.0.3.post3
webencodings==0.5.1
xcffib==0.12.1

And it should just need to install pdflatex to make it work, But let me try to make a container with the minimal dependency necessary for the build.
If you have a problem to convert an svg image.. maibe cairoSVG/Pillow is not installed, or out of date?

[wifasoi]

Ok i can reporduce it with:

FROM sphinxdoc/sphinx

WORKDIR /docs
ADD requirements.txt /docs
RUN export DEBIAN_FRONTEND=noninteractive && apt update && apt install -y latexmk texlive-latex-recommended texlive-fonts-recommended tex-gyre texlive-latex-extra && pip3 install -r requirements.txt

and execute the container with:
docker run --rm -v $(pwd):/docs <imagehash> make latexpdf

[numero-744]

Notice that there is also:

FROM sphinxdoc/sphinx-latexpdf

See https://hub.docker.com/r/sphinxdoc/sphinx

[numero-744]

I tried with the sphinx-latexpdf but I got the same error message

[wifasoi]

Found atleast one error: you need to install librsvg2-bin (don't know why imagemagik doesn't have this dependency on Debian)

[wifasoi]

The in the conf.py you can add render_using_wavedrompy = True, or install wavedrom.. I'm lazy and tried only with former, but it's better if we use wavedrom directly.

[numero-744]

Thanks, I'm adding npm etc to the Dockerfile. Then I'll have to add steps into actions to generate it, and I'm wondering: where do we want the pdf to be so that it can be downloaded?

[wifasoi]

as reference: sphinx-contrib/multiversion#70
Maybe we can put in the static folder, and customize the version picker with link to the files, or use the PR linked in the discussion above (need to check it first)

[numero-744]

@wifasoi I blame you: https://github.com/SpinalHDL/SpinalDoc-RTD/blame/883f8ad4e6c35d5c75e089f12e5261fcada35978/source/conf.py#L138

"I'm a big company. Is this project serious?" generates pdf doc "Err…*

[wifasoi]

LOL, guilty as charged :P
I should use the corporate appropriate placeholder: "Miao" :D

[numero-744]

So I pushed a branch with Docker configuration using npm version of wavedrom, and with a new Dockerfile which makes it possible to build pdf.

sphinx-contrib/multiversion#74 brings the feature we want but it is still open (last activity 1y ago).

EDIT: I'm testing using the version of multiversion of the PR

[numero-744]

I have pushed to the PR, it works for current branch:

(PDF opens PDF file, HTML is a broken link for now because I have not enabled it, it should not be displayed actually, I have reported it to the author of PR)

But for "all tags" it fails because it fails for one of the tags (so it just stops and do not even try subsequent tags):

LaTeX Warning: File `{assert/imag/fixpoint/highBitOperation}.png' not found on
input line 4866.

Note: things to add to the workflow, see https://github.com/sphinx-doc/docker/blob/master/latexpdf/Dockerfile + pdf.Dockerfile

[numero-744]

@wifasoi any idea about last message?

[Readon]

I have pushed to the PR, it works for current branch:

(PDF opens PDF file, HTML is a broken link for now because I have not enabled it, it should not be displayed actually, I have reported it to the author of PR)

But for "all tags" it fails because it fails for one of the tags (so it just stops and do not even try subsequent tags):

LaTeX Warning: File `{assert/imag/fixpoint/highBitOperation}.png' not found on
input line 4866.

Note: things to add to the workflow, see https://github.com/sphinx-doc/docker/blob/master/latexpdf/Dockerfile + pdf.Dockerfile

good work.

about the warning, if other images work then there should be an "e" in the path, the correct one is "asset/image/fixpoint/highBitOperation.png".

[numero-744]

So am I allowed to change the commit to the which the tags point to, to fix these links?

@Dolu1990 @Readon @wifasoi and maybe others?

[numero-744]

@Dolu1990

[Dolu1990]

So am I allowed to change the commit to the which the tags point to, to fix these links?

Ahh sure sure ^^

[numero-744]

Okay I fixed tag v1.3.8, now multiversion works!

fc210e6

By the way I notice we have branches named vX.X.X which are not tags, is it something we want?

No I will try adding it to the workflow in #133

[Dolu1990]

Okay I fixed tag v1.3.8, now multiversion works!

Nice ^^

By the way I notice we have branches named vX.X.X which are not tags, is it something we want?

i think we can get ride of them.

[numero-744]

Ok I'll remove these branches later™

[numero-744]

There is also branch 1.7.3, do I remove it? @Dolu1990

[numero-744]

For dev and old_dev I am wondering, should dev be used instead of master, like for SpinalHDL repository?