Zuul jobs fail running tox-docs

[John Kung]

Brief Description
-----------------
Zuul tox docs fail to pass running tox docs

Severity
--------

Major: Blocks gerrit code merge at Zuul gate

Steps to Reproduce
------------------
Run tox docs test

Expected Behavior
------------------
tox should pass

Actual Behavior
----------------

Sample Traceback observed in Zuul job:

docs: 426 I exit 0 (0.01 seconds) /home/zuul/src/opendev.org/starlingx/metal> rm -rf doc/build pid=1588 [tox/execute/api.py:279]
docs: 427 W commands[1]> sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html [tox/tox_env/api.py:427]
Running Sphinx v6.2.1

Warning, treated as error:
Invalid configuration value found: 'language = None'. Update your configuration to a valid language code. Falling back to 'en' (English).
docs: 1007 C exit 2 (0.58 seconds) /home/zuul/src/opendev.org/starlingx/metal> sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html pid=1593 [tox/execute/api.py:279]
  docs: FAIL code 2 (0.67=setup[0.08]+cmd[0.01,0.58] seconds)
  evaluation failed :( (0.80 seconds)

Test Activity
-------------
Zuul Merge

Workaround
----------
Clamp sphinx version.

Reproducibility
---------------
Reproducible

System Configuration
--------------------
n/a

Branch/Pull Time/Commit
-----------------------
Late August 2023

Last Pass
---------
Prior to sphinx upversion.

Timestamp/Logs
--------------
See section above.

Test Activity
-------------
n/a

Workaround
----------
n/a

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.opendev.org/c/starlingx/metal/+/893104

[John Kung (john-kung)]

Another fix in gui repo:
https://review.opendev.org/c/starlingx/gui/+/892575/11/doc/requirements.txt

[Leonardo Fagundes Luz Serrano (lfagunde)]

A related bug:
https://bugs.launchpad.net/starlingx/+bug/1976377

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.opendev.org/c/starlingx/tools/+/893165

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/c/starlingx/metal/+/893104
Committed: https://opendev.org/starlingx/metal/commit/7a1fb6333c97bb124d3d4330d599a792ad7f9180
Submitter: "Zuul (22348)"
Branch: master

commit 7a1fb6333c97bb124d3d4330d599a792ad7f9180
Author: John Kung <email address hidden>
Date: Tue Aug 29 14:22:10 2023 -0400

    Fix tox-docs failing sphinx

    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:
    https://github.com/sphinx-doc/sphinx/issues/10062
    https://github.com/sphinx-doc/sphinx/issues/10474

    Partial-Bug: 1976377
    Partial-Bug: 2033431

    Change-Id: I882faa7ce199d8817598980b9dc5090b4e1af57d
    Signed-off-by: John Kung <email address hidden>

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/c/starlingx/tools/+/893165
Committed: https://opendev.org/starlingx/tools/commit/4454fad3a8261526a1bc96e9fa3ac67dc5f1e838
Submitter: "Zuul (22348)"
Branch: master

commit 4454fad3a8261526a1bc96e9fa3ac67dc5f1e838
Author: Luan Nunes Utimura <email address hidden>
Date: Wed Aug 30 09:25:39 2023 -0300

    Fix tox-docs failing sphinx

    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:
    https://github.com/sphinx-doc/sphinx/issues/10062
    https://github.com/sphinx-doc/sphinx/issues/10474

    Partial-Bug: 1976377
    Partial-Bug: 2033431

    Change-Id: I089f9afe7e75b5ceabe3bf05d14ffd76e33ac3ab
    Signed-off-by: Luan Nunes Utimura <email address hidden>

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: f/antelope
Review: https://review.opendev.org/c/starlingx/tools/+/893246

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.opendev.org/c/starlingx/kernel/+/893301

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/c/starlingx/kernel/+/893301
Committed: https://opendev.org/starlingx/kernel/commit/5a1dfa827419831eddf6b46f235e239ee7563344
Submitter: "Zuul (22348)"
Branch: master

commit 5a1dfa827419831eddf6b46f235e239ee7563344
Author: M. Vefa Bicakci <email address hidden>
Date: Thu Aug 31 01:29:57 2023 +0000

    doc: Fix Zuul/tox failures

    This commit resolves the Zuul/tox failures encountered when running
    sphinx to generate documentation, which in turn prevents merging changes
    that are otherwise fine:

    ```
    docs: 350 W commands[1]> sphinx-build -a -E -W -d doc/build/doctrees \
      -b html doc/source doc/build/html [tox/tox_env/api.py:427]
    Running Sphinx v6.2.1

    Warning, treated as error:
    Invalid configuration value found: 'language = None'. Update your \
      configuration to a valid language code. Falling back to 'en' \
      (English).
    docs: 723 C exit 2 (0.37 seconds) \
        /home/zuul/src/opendev.org/starlingx/kernel> \
        sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source \
        doc/build/html pid=1720 [tox/execute/api.py:279]
      docs: FAIL code 2 (0.44=setup[0.07]+cmd[0.00,0.37] seconds)
      evaluation failed :( (0.54 seconds)
    ```

    This issue was fixed for another StarlingX repository (tools) with
      https://review.opendev.org/c/starlingx/tools/+/893165
    from which this commit is inspired.

    The issue is related to a Sphinx update that requires the language
    parameter to be specified:
      https://github.com/sphinx-doc/sphinx/issues/10062
      https://github.com/sphinx-doc/sphinx/issues/10474

    Partial-Bug: 1976377
    Partial-Bug: 2033431

    Change-Id: Ic20fec5145b1a4ddb12051f018614562a4773b95
    Signed-off-by: M. Vefa Bicakci <email address hidden>

[Bruno Drugowick Muniz (brunomuniz)]

The tox for the docs repo is failing independently as well, so I opened this LP: https://bugs.launchpad.net/starlingx/+bug/2030817. To fix, I proposed: https://review.opendev.org/c/starlingx/docs/+/890833, which has an ongoing discussion about the right way to fix this.

Could these LPs be related?

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/c/starlingx/tools/+/893246
Committed: https://opendev.org/starlingx/tools/commit/0f1383f4b8e4a75590db300f327a47b88c42ed57
Submitter: "Zuul (22348)"
Branch: f/antelope

commit 0f1383f4b8e4a75590db300f327a47b88c42ed57
Author: Luan Nunes Utimura <email address hidden>
Date: Wed Aug 30 09:25:39 2023 -0300

    Fix tox-docs failing sphinx

    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:
    https://github.com/sphinx-doc/sphinx/issues/10062
    https://github.com/sphinx-doc/sphinx/issues/10474

    Partial-Bug: 1976377
    Partial-Bug: 2033431

    Change-Id: I089f9afe7e75b5ceabe3bf05d14ffd76e33ac3ab
    Signed-off-by: Luan Nunes Utimura <email address hidden>
    (cherry picked from commit 4454fad3a8261526a1bc96e9fa3ac67dc5f1e838)

[OpenStack Infra (hudson-openstack)]

Change abandoned by "Junfeng Li <email address hidden>" on branch: master
Review: https://review.opendev.org/c/starlingx/update/+/894301

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.opendev.org/c/starlingx/test/+/895180

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.opendev.org/c/starlingx/docs/+/895182

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/c/starlingx/docs/+/895182
Committed: https://opendev.org/starlingx/docs/commit/4a39495694006b7e1b58f5a14cff4a2c9898b7bd
Submitter: "Zuul (22348)"
Branch: master

commit 4a39495694006b7e1b58f5a14cff4a2c9898b7bd
Author: Scott Little <email address hidden>
Date: Thu Sep 14 10:50:44 2023 -0400

    doc: Fix Zuul/tox failures

    This commit resolves the Zuul/tox failures encountered when running
    sphinx to generate documentation, which in turn prevents merging
    changes that are otherwise fine:

    The issue is related to a Sphinx update that requires the language
    parameter to be specified:
          https://github.com/sphinx-doc/sphinx/issues/10062
          https://github.com/sphinx-doc/sphinx/issues/10474

    Partial-Bug: 1976377
    Partial-Bug: 2033431
    Change-Id: I23aead0ecf470ffdff5b387e39fa1e0cafb608da
    Signed-off-by: Scott Little <email address hidden>

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/c/starlingx/test/+/895180
Committed: https://opendev.org/starlingx/test/commit/12494275f6c349f06cb8ee27c913398fe0ad0b6e
Submitter: "Zuul (22348)"
Branch: master

commit 12494275f6c349f06cb8ee27c913398fe0ad0b6e
Author: Scott Little <email address hidden>
Date: Thu Sep 14 10:46:44 2023 -0400

    doc: Fix Zuul/tox failures

    This commit resolves the Zuul/tox failures encountered when running
    sphinx to generate documentation, which in turn prevents merging
    changes that are otherwise fine:

    The issue is related to a Sphinx update that requires the language
    parameter to be specified:
          https://github.com/sphinx-doc/sphinx/issues/10062
          https://github.com/sphinx-doc/sphinx/issues/10474

    Partial-Bug: 1976377
    Partial-Bug: 2033431
    Signed-off-by: Scott Little <email address hidden>
    Change-Id: Ifa3d4638955ddd2ff9f2acd9225657c16958a03a

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: f/antelope
Review: https://review.opendev.org/c/starlingx/metal/+/903826

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: r/stx.8.0
Review: https://review.opendev.org/c/starlingx/tools/+/911099

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/c/starlingx/tools/+/911099
Committed: https://opendev.org/starlingx/tools/commit/67029387e23a7a099aeac26a819a2f42009afd9e
Submitter: "Zuul (22348)"
Branch: r/stx.8.0

commit 67029387e23a7a099aeac26a819a2f42009afd9e
Author: Luan Nunes Utimura <email address hidden>
Date: Wed Aug 30 09:25:39 2023 -0300

    Fix tox-docs failing sphinx

    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:
    https://github.com/sphinx-doc/sphinx/issues/10062
    https://github.com/sphinx-doc/sphinx/issues/10474

    Partial-Bug: 1976377
    Partial-Bug: 2033431

    Change-Id: I089f9afe7e75b5ceabe3bf05d14ffd76e33ac3ab
    Signed-off-by: Luan Nunes Utimura <email address hidden>
    (cherry picked from commit 4454fad3a8261526a1bc96e9fa3ac67dc5f1e838)

[OpenStack Infra (hudson-openstack)]

Change abandoned by "Bob Church <email address hidden>" on branch: f/antelope
Review: https://review.opendev.org/c/starlingx/metal/+/903826
Reason: This has languished. Abandoning. If @<email address hidden> wants it reinstated, can do so.