Bug: Pipeline fails if their is no connection to the versions.json file

[tomboehling]

You have implemented a new check that fails if the connection to the file is not possible.

There could be many reasons for a connection error:

• Restricted access to the url (not possible in pipeline)
• first run of pipeline
• file is created later in the pipeline

pydata-sphinx-theme/src/pydata_sphinx_theme/__init__.py

Lines 71 to 74 in cdc2e8e

	if urlparse(json_url).scheme in ["http", "https"]:
	content = requests.get(json_url).text
	else:
	content = Path(env.srcdir, json_url).read_text()

[12rambau]

I actually added this test to give feedback to the user if the .json file was malformed. As the test is mainly for development purposes (e.g. my dropdown doesn't work what have I done ?) maybe we should discard the test if it's using a distant file ?

[tomboehling]

I don't know what might be the best solution. If you could deactivate the test for remote files, this will work for me. But I understand your idea of testing the version file.

[callumforrester]

I'm unsure if warning immediately is the right thing to do. Maybe it would also be best to add a local failover option, so the docs could always be built offline, or else a config option to disable the warning.

[coretl]

My workflow is:

• Start from a template repo that points the switcher to a non-existent json file on github.io
• Write the docs and push to GitHub
• Sphinx warnings are treated as errors
• GitHub builds the docs and makes the json and pushes both to github.io

This fails to bootstrap at the moment, as the workflow that would push the json can't get far enough to push the json.

I suggest adding an environment variable to allow the checking to be skipped. We would then run the checking locally, but disable it in CI so that the bootstrapping can occur.

[12rambau]

I'm unsure if warning immediately is the right thing to do. Maybe it would also be best to add a local failover option, so the docs could always be built offline, or else a config option to disable the warning.

The Warnings I'm talking about are Sphinx Warnings, there are not preventing the build of the documentation.

[drammock]

The Warnings I'm talking about are Sphinx Warnings, there are not preventing the build of the documentation.

I think the problem though is that many CI configurations treat Sphinx warnings as errors, to make sure that things like broken cross-references don't get introduced. This means in a build -> deploy pipeline the deploy step won't happen unless the sphinx build is warning-free not just error-free.

[12rambau]

and then what about what we are doing here with expected warnings ?

pydata-sphinx-theme/.github/workflows/tests.yml

Line 66 in adc8b1d

run: |

[drammock]

and then what about what we are doing here with expected warnings ?

That is for our doc builds. we expect many warnings because we intentionally include the kitchen sink page which has things like broken cross-references on purpose.

For consumers of the theme, this will generally not be the case (no intentional malformed rST), so many projects use the -W flag to sphinx-build which causes sphinx to treat warnings as errors (for the reason I mentioned above).

I'm starting to wonder if I'm not understanding something though. Is it the case that the warning raised by your test in the theme's __init__.py will be caught by sphinx (and possibly elevated to an error if the user used the -W flag)?

[12rambau]

That is for our doc builds. we expect many warnings because we intentionally include the kitchen sink page which has things like broken cross-references on purpose.

Note that as you mentioned in #937, no shinx warning is raised from the kitchen think (I'm still surprised by this one)

I'm starting to wonder if I'm not understanding something though. Is it the case that the warning raised by your test in the theme's init.py will be caught by sphinx (and possibly elevated to an error if the user used the -W flag)?

At the moment no and that's the main subject of the issue. But I've started #993 to transform regular exceptions into Sphinx warning.

[coretl]

I'm starting to wonder if I'm not understanding something though. Is it the case that the warning raised by your test in the theme's __init__.py will be caught by sphinx (and possibly elevated to an error if the user used the -W flag)?

Here's an example using the #993 branch with a malformed json file. The logging.warning appears to be caught by sphinx as a warning, and the -W flag promotes it to an error:
https://github.com/epics-containers/epics-containers-cli/actions/runs/3219562432/jobs/5265389325

Without the -W flag it shows as a warning but doesn't fail the build:
https://github.com/epics-containers/epics-containers-cli/actions/runs/3219724805/jobs/5265477373

(the json file in this example really is malformed, I misread the docs about which keys were optional)

[ClementPinard]

Hello,

to add on the pile, we too had our pipeline broken by upgrading to 0.11.0, because the version switcher was uploaded with the first tag all at once with gitlab pages.

Looks like #993 will solve our issue, thanks !

Any idea when this fix will be installable in a 0.11.1 or 0.12.0 ?

[12rambau]

that was the last blocking issue for the next release so very soon