Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add_js_file(..., async="async") causes SyntaxError #10013

Closed
ftnext opened this issue Dec 24, 2021 · 1 comment · Fixed by #10017
Closed

add_js_file(..., async="async") causes SyntaxError #10013

ftnext opened this issue Dec 24, 2021 · 1 comment · Fixed by #10017
Labels
type:enhancement enhance or introduce a new feature

Comments

@ftnext
Copy link

ftnext commented Dec 24, 2021

Is your feature request related to a problem? Please describe.
I want to put <script src="..." async="async"></script> tag in built HTML.
I found the example in https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_js_file and I tried it.

In conf.py,

def setup(app):
    app.add_js_file('example.js', async="async")
$ make html
Sphinx v4.3.1 を実行中

Configuration error:
設定ファイルに文法エラーが見つかりました: invalid syntax (conf.py, line 63)

make: *** [html] Error 2

Environment

  • Python 3.9.4
  • Sphinx 4.3.1

Problem: We cannot use async as parameter of add_js_file in Python 3.7 or later.
https://docs.python.org/3/whatsnew/3.7.html#summary-release-highlights

async and await are now reserved keywords.

Describe the solution you'd like
Proposal: add a parameter to add_js_file to specify async or not.
add_js_file(filename: str, priority: int = 500, load_async: bool = False, **kwargs: Any)

app.add_js_file('example.js', load_async=False)
# => <script src="_static/example.js"></script>

app.add_js_file('example.js', load_async=True)
# => <script src="_static/example.js" async></script>

Describe alternatives you've considered
If my proposal is not implemented, I would like to update the example of the document https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_js_file.

Options:

  1. Show Python version limitation
app.add_js_file('example.js', async="async")  # only Python 3.6 or earlier (cause SyntaxError in Python 3.7 or later)
# => <script src="_static/example.js" async="async"></script>
  1. Remove async="async" example
    In 2022, Python 3.6 will no longer be supported.
    ref: https://www.python.org/dev/peps/pep-0494/#lifespan
    The example causes SyntaxError in Python 3.7 and later, so It seems better to remove it than to keep it in the document.

Additional context
N/A

@ftnext ftnext added the type:enhancement enhance or introduce a new feature label Dec 24, 2021
@tk0miya
Copy link
Member

tk0miya commented Dec 25, 2021

OMG, it must be a bug of our document. Thank you for reporting.

There are two kinds of loading methods; async and defer. So it would be better to be able to specify one of them as a value instead of parameter name (ex. loading_method="async"). I'll consider what better name is.

tk0miya added a commit to tk0miya/sphinx that referenced this issue Dec 25, 2021
tk0miya added a commit to tk0miya/sphinx that referenced this issue Dec 25, 2021
tk0miya added a commit that referenced this issue Dec 26, 2021
Close #10013: html: Allow to change the loading method of JavaScript
AA-Turner pushed a commit to AA-Turner/sphinx that referenced this issue Dec 29, 2021
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jan 25, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
type:enhancement enhance or introduce a new feature
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants