doc: switch to sphinxcontrib.rsvgconverter

[proppy]

Apparently the pdf build failure (see https://github.com/google/gf180mcu-pdk/issues/82#issuecomment-1284785504) makes the final RTD documentation push fails.

Fixes #82 (hopefully)

Also enabled PDF build in https://readthedocs.org/dashboard/gf180mcu-pdk/advanced/

TEST=https://gf180mcu-pdk--87.org.readthedocs.build/en/87/digital/Digital.html

/cc @cbalint13 @mkkassem

[proppy]

curious if @umarcor has guidance on the proper way to test readthedocs changes extensively, so that we can prevent this from happening again (pdf changes that break the html publication); found the following actions that could be useful:

• https://github.com/dfm/rtds-action
• https://github.com/DavidLeoni/readthedocs-to-actions
• https://github.com/ammaraskar/sphinx-action

[cbalint13]

curious if @umarcor has guidance on the proper way to test readthedocs changes extensively, so that we can prevent this from happening again (pdf changes that break the html publication); found the following actions that could be useful:

• https://github.com/dfm/rtds-action
• https://github.com/DavidLeoni/readthedocs-to-actions
• https://github.com/ammaraskar/sphinx-action

• There is this limitation of rthedocs that still does not show us PDF generation steps in PR stage (only merged):
  • https://gf180mcu-pdk--87.org.readthedocs.build/en/87/digital/Digital.html
• With such feedback limitation on their buildsystem PDF steps are hard to see, can't imagine how to "automate" in PR stage.

---

@umarcor @proppy

To sum experience up so far:

• sphinx.ext.imgconverter using "imagemagick" backend fail on blank SVG (skywater had no such and it passed).
• Expicit sphinx-svg2pdfconverter request still not pick up inkscape but convert, probably their docker miss it here

Lets see if this sphinxcontrib.rsvgconverter now invokes proper tools (other than imagemagick). In case this here works, the trick can be enabled on skywater too, generated images would be smoother (as per the docs).

[proppy]

Expicit sphinx-svg2pdfconverter request still not pick up inkscape but convert, probably their docker https://github.com/readthedocs/readthedocs-docker-images/issues/70

my understanding (from reading https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter#installation) is that inkscape would only get picked if you add sphinxcontrib.inkscapeconverter to the extensions.

Here we add sphinxcontrib.rsvgconverter which seems to depends on rsvg-convert which has been added to their image w/ https://github.com/readthedocs/readthedocs-docker-images/pull/79.

[proppy]

can't imagine how to "automate" in PR stage.

what I was thinking is that we could mimic what the readthedocs integration is doing in an action (i.e: run the same command on top of the same container image) to proof test our changes.

[cbalint13]

can't imagine how to "automate" in PR stage.

what I was thinking is that we could mimic what the readthedocs integration is doing in an action (i.e: run the same command on top of the same container image) to proof test our changes.

@proppy

uhh,

• Q: Does that "PDF Enable" activated PDF builds too in open PR stage ?
• It does't seems to work, but perhaps you enabled it after this very PR was opened (?!)

We could check / or ask them (rthdocs) why in PR stage the PDF generation is disabled. If there is no other way then yes a parallel docker build might be ultimate just to have PDF build feedback.

[proppy]

Q: Does that "PDF Enable" activated PDF builds too in open PR stage ?

It doesn't seems so, I suspect it's overridden by whatever is is .readthedocs.yaml.

[umarcor]

@proppy see:

• github.com/buildthedocs
  • buildthedocs/btd
  • pyTooling/Actions: .github/workflows/BuildTheDocs.yml
• https://github.com/ghdl/ghdl/blob/5cbfa82ebe90ac1016899c9cbecbaf07daa7e588/.github/workflows/Test.yml#L65-L69

    - name: '📓 BuildTheDocs (BTD)'
      uses: buildthedocs/btd@v0
      with:
        token: ${{ github.token }}
        skip-deploy: ${{ github.event_name == 'pull_request' }}

  and ghdl/ghdl: .btd.yml

• https://github.com/dbhi/qus/blob/7e69017991bfca24fbf5cac6bc7ae14f26cfc52a/.github/workflows/Test.yml#L13-L37 and dbhi/qus: .btd.yml
• https://github.com/hdl/containers/blob/339752001a86d4029e58126f24b46efaad42c063/.github/workflows/doc.yml#L81-L100 and hdl/containers: .btd.yml
• hdl/constraints: .github/workflows/doc.yml and hdl/constraints: .btd.yml
• hdl/conda-eda: .github/workflows/docs.yml and hdl/conda-eda: .btd.yml
• umarcor/osvb: .github/workflows/Doc.yml and umarcor/osvb: .btd.yml
• See also the repos in github.com/edaa-org.

See also manual equivalents (without using an Action):

• https://github.com/chipsalliance/f4pga/blob/e1cd038f06c7161b27afd0073fb507da2b8e5a9e/.github/workflows/Pipeline.yml#L63-L101
• https://github.com/VUnit/vunit/blob/master/.github/workflows/docs.yml

[cbalint13]

@proppy ,

Bit more on SVG backend related:

• On newer releases even sphinxcontrib.rsvgconverter fails :)

  
  $ rsvg-convert gf180mcu_fd_sc_mcu7t5v0__endcap.schematic.svg
  The SVG gf180mcu_fd_sc_mcu7t5v0__endcap.schematic.svg has no dimensions

$ rsvg-convert -v rsvg-convert version 2.54.5

* I am using these build varieties to native rpm packages: https://copr.fedorainfracloud.org/coprs/rezso/VLSI/build/4962277/

---

Sticking to ```sphinx.ext.imgconverter``` (native, not ```contrib```) always works with ```imagemagick``` & ```inkscape```  (required).
The best would be in future to avoid  trow such SVG (not so legit ones) to latex/sphinx flow, we could fix that in the future.

Thanks a lot for helping,
~Cristian.