Skip to content

To improve accessibility, set language in conf.py using sphinx-quickstart #10062

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.

Sign up for GitHub

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

Jump to bottom
Closed
bertiewooster opened this issue Jan 7, 2022 · 3 comments
Closed

To improve accessibility, set language in conf.py using sphinx-quickstart #10062

bertiewooster opened this issue Jan 7, 2022 · 3 comments
Labels
internals:internationalisation type:enhancement enhance or introduce a new feature
Milestone
5.0.0

Comments

@bertiewooster
Copy link

bertiewooster commented Jan 7, 2022 •
edited
Loading

Is your feature request related to a problem? Please describe.
By default, Sphinx documentation does not include the language, for example in docs/conf.py
language = 'en'

result in built web pages:
<html lang="en">

This leads to the following accessibility issue identified by Lighthouse:

<html> element does not have a [lang] attribute

If a page doesn't specify a lang attribute, a screen reader assumes that the page is in the default language that the user chose when setting up the screen reader. If the page isn't actually in the default language, then the screen reader might not announce the page's text correctly. Learn more.`

Also, Sphinx sites thus do not by default take advantage of the features offered by setting the language.

This accessibility issue is present in major sites including NumPy.

Describe the solution you'd like
User already enters language when they run sphinx-quickstart:

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]:

so it should automatically set that language value in the generated conf.py file.

It would also be nice if there was some prompt to set the language of existing Sphinx installations, upon an update of Sphinx version, or build of the documentation, for example.

Describe alternatives you've considered
Status quo, which retains accessibility issue.

Additional context
Related issue: #10056.
@bertiewooster bertiewooster added the type:enhancement enhance or introduce a new feature label Jan 7, 2022
tk0miya added a commit to tk0miya/sphinx that referenced this issue Jan 8, 2022
@tk0miya
Close sphinx-doc#10062: Change the default language to 'en'
3486249 
Change the default language to `'en'` if any language is not set in
`conf.py`.
@tk0miya tk0miya mentioned this issue Jan 8, 2022
Merged
@tk0miya tk0miya added this to the 5.0.0 milestone Jan 8, 2022
tk0miya added a commit to tk0miya/sphinx that referenced this issue Jan 8, 2022
@tk0miya
Close sphinx-doc#10062: Change the default language to 'en'
bdc0b9b 
Change the default language to `'en'` if any language is not set in
`conf.py`.
@bertiewooster
Copy link
Author

@tk0miya Thank you for addressing this a11y and i18n issue!

tk0miya added a commit to tk0miya/sphinx that referenced this issue Jan 11, 2022
@tk0miya
Close sphinx-doc#10062: Change the default language to 'en'
e4e58a4 
Change the default language to `'en'` if any language is not set in
`conf.py`.
tk0miya added a commit that referenced this issue Jan 12, 2022
@tk0miya
Merge pull request #10067 from tk0miya/10062_change_default_language_…
c5a888f 
…to_en

Close #10062: Change the default language to 'en'
@tk0miya tk0miya modified the milestones: 5.0.0, 5.x May 2, 2022
@befeleme befeleme mentioned this issue May 24, 2022
Closed
starlingx-github pushed a commit to starlingx/config that referenced this issue May 31, 2022
@albailey-wr
Fix tox-docs failing sphinx
43ec9b8 
A new version of sphinx was released May 29 2022
which requires a language setting in config otherwise
a warning (treated as error) causes the sphinx operation
to fail.

Updating a file header to trigger zuul.
Updated the sphinx config file to correct the issue.

The sphinx behavioural change is mentioned here:
sphinx-doc/sphinx#10062
sphinx-doc/sphinx#10474

Closes-Bug: #1976377
Signed-off-by: Al Bailey <al.bailey@windriver.com>
Change-Id: I4d489a7bb8f579c894081bedba8ac3638a7eae1d
starlingx-github pushed a commit to starlingx/ha that referenced this issue May 31, 2022
@albailey-wr
Fix tox-docs failing sphinx
d4ea342 
A new version of sphinx was released May 29 2022
which requires a language setting in config otherwise
a warning (treated as error) causes the sphinx operation
to fail.

Updated the sphinx config file to correct the issue.

The sphinx behavioural change is mentioned here:
sphinx-doc/sphinx#10062
sphinx-doc/sphinx#10474

Partial-Bug: #1976377
Signed-off-by: Al Bailey <al.bailey@windriver.com>
Change-Id: I5c5c501e23744aa0dbaf4280ed5abcd27442f20f
starlingx-github pushed a commit to starlingx/upstream that referenced this issue May 31, 2022
@albailey-wr
Fix tox-docs failing sphinx
2f9f57b 
A new version of sphinx was released May 29 2022
which requires a language setting in config otherwise
a warning (treated as error) causes the sphinx operation
to fail.

Updated the sphinx config file to correct the issue.

The sphinx behavioural change is mentioned here:
sphinx-doc/sphinx#10062
sphinx-doc/sphinx#10474

Partial-Bug: #1976377
Signed-off-by: Al Bailey <al.bailey@windriver.com>
Change-Id: I5fea877955c0d9b875c31f0b64bc8f3bced5c208
@hugovk hugovk mentioned this issue Jun 4, 2022
Merged
@hugovk
Copy link
Contributor

hugovk commented Jun 4, 2022

This can be closed now #10067 is merged and released.

@AA-Turner
Copy link
Member

Thanks Hugo!

starlingx-github pushed a commit to starlingx/nfv that referenced this issue Jun 5, 2022
@hmatsui47
Fix tox-docs failing sphinx
c819a65 
A new version of sphinx was released May 29 2022
which requires a language setting in config otherwise
a warning (treated as error) causes the sphinx operation
to fail.

Updating a file header to trigger zuul.
Updated the sphinx config file to correct the issue.

The sphinx behavioural change is mentioned here:
sphinx-doc/sphinx#10062
sphinx-doc/sphinx#10474

Note: The bug referenced below is for the config repo,
      but it affects multiple StarlingX repositories.

Closes-Bug: 1976377
Change-Id: I7bb7886f27ce6190f8e23270efc1aadb7364fc90
Signed-off-by: Heitor Matsui <HeitorVieira.Matsui@windriver.com>
rennerocha added a commit to rennerocha/spidermon that referenced this issue Jun 6, 2022
@rennerocha
Fix Sphinx 5 warning by setting docs language
1b3474d 
Introduced in Sphinx 5.x:
sphinx-doc/sphinx#10062

We need to define a language in our conf.py
@rennerocha rennerocha mentioned this issue Jun 6, 2022
Merged
rennerocha added a commit to scrapinghub/spidermon that referenced this issue Jun 6, 2022
@rennerocha
Fix Sphinx 5 warning by setting docs language
a5d32c8 
Introduced in Sphinx 5.x:
sphinx-doc/sphinx#10062

We need to define a language in our conf.py
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 5, 2022
@AA-Turner AA-Turner modified the milestones: 5.x, 5.0.0 Oct 4, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
internals:internationalisation type:enhancement enhance or introduce a new feature
Projects
None yet
Milestone
5.0.0
Development

No branches or pull requests
4 participants
@tk0miya @hugovk @bertiewooster @AA-Turner