Fix QLLexer instance as argument to add_lexer

[mbg]

add_lexer requires a type as argument in versions of sphinx >= 2.1 (docs). Currently, an instance of QLLexer is passed to it, which causes the docs build to fail if a version of Sphinx >= 3 is used. This PR fixes this so that the documentation can be built successfully.

[adityasharad]

Try this. The callable builtin should tell us whether an object is indeed callable. This way we can remain robust to different versions of Sphinx + pygments being installed, without breaking either local or CI usage.

Suggested change

	sphinx.add_lexer("ql", QLLexer)
	sphinx.add_lexer("ql", QLLexer() if callable(QLLexer) else QLLexer)

There are actually 3 places in the code we make this call:

• docs/codeql/conf.py (here)
• docs/codeql/ql-training/conf.py
• documentation/restructuredtext/codeql-cli/conf.py within the internal repo

Would you mind updating the first 2 locations in this PR, and then we can tackle the third in an internal PR?

[mbg]

Thanks for the suggestion! Unfortunately, this fails with:

Exception occurred:
  File "/opt/homebrew/lib/python3.10/site-packages/sphinx/highlighting.py", line 130, in get_lexer
    lexer = lexer_classes[lang](**opts)
TypeError: 'QLLexer' object is not callable

I think the problem may be that QLLexer is callable regardless of the Sphinx version used. It is just add_lexer that has different expectations of how you pass the lexer in, depending on the version.

[adityasharad]

Hmph yes good point. Thank you for trying. I wonder if we can detect from within Python what the Sphinx version is? If not I think the principled solution is the one in the internal issue - pin to a specific version of the packages.

[smowton]

@adityasharad if pinning Sphinx or otherwise depending on a consistent version across environments is backlogged, shall we merge this?

[adityasharad]

As currently written I think this PR is safe enough since it will allow both local and CI usage to keep working 👍. Rerunning tests.

[mbg]

I might be wrong since this was three months ago, but if I remember correctly merging this PR wouldn't do very much. It makes effectively no change in CI and the fallback doesn't actually work with newer versions of Sphinx.

[adityasharad]

Just realised the same thing from #11353 (comment) !