PCI configuration documentation renders with smart quotes

[Lee Yarwood]

https://docs.openstack.org/nova/latest/configuration/config.html#pci

For example, an alias example line renders as:

alias = { “name”: “QuickAssist”, “product_id”: “0443”, “vendor_id”: “8086”, “device_type”: “type-PCI”, “numa_policy”: “required” }

Instead of the valid:

alias = { "name": "QuickAssist", "product_id": "0443", "vendor_id": "8086", "device_type": "type-PCI", "numa_policy": "required" }

[Matt Riedemann (mriedem)]

This actually seems to be something with the sphinx extension, not something in our docs, because you can see it on other options too:

https://docs.openstack.org/nova/latest/configuration/config.html#DEFAULT.rpc_zmq_bind_address

[Matt Riedemann (mriedem)]

The generated sample file is OK:

# ZeroMQ bind address. Should be a wildcard (*), an ethernet interface, or IP.
# The "host" option should point or resolve to this address. (string value)
#rpc_zmq_bind_address = *

[Matt Riedemann (mriedem)]

The problem would be in here I'd think, but not sure where:

https://github.com/openstack/oslo.config/blob/master/oslo_config/sphinxext.py

[Doug Hellmann (doug-hellmann)]

The zmq option example is coming from http://git.openstack.org/cgit/openstack/oslo.messaging/tree/oslo_messaging/_drivers/zmq_driver/zmq_options.py#n33

The text has regular double quotes. Sphinx converts those to "smart" quotes by default. There is an option to disable that and you could change that setting in the nova doc build if you want. We could also change the help text to use back-ticks instead of double quotes.

Do you think the smart quotes are somehow misleading? Or are they causing problems? I guess they're not the best way to indicate the name of a configuration option.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/553730

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/553730
Committed: https://git.openstack.org/cgit/openstack/nova/commit/?id=75fc30090133c31316e6ae790568f1b622807d0c
Submitter: Zuul
Branch: master

commit 75fc30090133c31316e6ae790568f1b622807d0c
Author: Lee Yarwood <email address hidden>
Date: Fri Mar 16 09:37:19 2018 +0000

    docs: Disable smartquotes

    This change should then allow all configuration examples to be copied
    from the docs directly into nova.conf without resulting in Unicode
    errors when these options are then parsed.

    Note that this option is deprecated and replaced in Sphinx 1.6.6 [1] by
    the smartquotes configurable. A future change will need to land to
    switch between these, for now we will use and backport the
    html_use_smartypants option.

    [1] http://www.sphinx-doc.org/en/stable/config.html#confval-smartquotes

    Change-Id: I6c47a0d74e5b5a03bc030a7e45cc7783f22ddadf
    Closes-bug: #1755783

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/553860

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/queens
Review: https://review.openstack.org/554188

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/pike
Review: https://review.openstack.org/554189

[OpenStack Infra (hudson-openstack)]

Related fix proposed to branch: master
Review: https://review.openstack.org/554632

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/554188
Committed: https://git.openstack.org/cgit/openstack/nova/commit/?id=68b92745bf38133c5d96a8dbadb8c0d09af8c944
Submitter: Zuul
Branch: stable/queens

commit 68b92745bf38133c5d96a8dbadb8c0d09af8c944
Author: Lee Yarwood <email address hidden>
Date: Fri Mar 16 09:37:19 2018 +0000

    docs: Disable smartquotes

    This change should then allow all configuration examples to be copied
    from the docs directly into nova.conf without resulting in Unicode
    errors when these options are then parsed.

    Note that this option is deprecated and replaced in Sphinx 1.6.6 [1] by
    the smartquotes configurable. A future change will need to land to
    switch between these, for now we will use and backport the
    html_use_smartypants option.

    [1] http://www.sphinx-doc.org/en/stable/config.html#confval-smartquotes

    Change-Id: I6c47a0d74e5b5a03bc030a7e45cc7783f22ddadf
    Closes-bug: #1755783
    (cherry picked from commit 75fc30090133c31316e6ae790568f1b622807d0c)

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/554189
Committed: https://git.openstack.org/cgit/openstack/nova/commit/?id=3a083e756e2c38d69add93c18956030ef8248494
Submitter: Zuul
Branch: stable/pike

commit 3a083e756e2c38d69add93c18956030ef8248494
Author: Lee Yarwood <email address hidden>
Date: Fri Mar 16 09:37:19 2018 +0000

    docs: Disable smartquotes

    This change should then allow all configuration examples to be copied
    from the docs directly into nova.conf without resulting in Unicode
    errors when these options are then parsed.

    Note that this option is deprecated and replaced in Sphinx 1.6.6 [1] by
    the smartquotes configurable. A future change will need to land to
    switch between these, for now we will use and backport the
    html_use_smartypants option.

    [1] http://www.sphinx-doc.org/en/stable/config.html#confval-smartquotes

    Change-Id: I6c47a0d74e5b5a03bc030a7e45cc7783f22ddadf
    Closes-bug: #1755783
    (cherry picked from commit 75fc30090133c31316e6ae790568f1b622807d0c)

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/nova 17.0.2 release.

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/nova 16.1.1 release.

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/553860
Committed: https://git.openstack.org/cgit/openstack/oslo.config/commit/?id=03ff144f0bf386982d379d18aeb9183146a05fd5
Submitter: Zuul
Branch: master

commit 03ff144f0bf386982d379d18aeb9183146a05fd5
Author: Stephen Finucane <email address hidden>
Date: Fri Mar 16 16:53:37 2018 +0000

    sphinxext: Start parsing 'Opt.help' as rST

    Users expect this to be parsed as rST and write their docstrings
    accordingly. This has the potential to introduce warnings for users with
    improperly formatted rST and these warnings can be promoted to errors if
    'sphinx-build' is used with the '-W' option. As a result, we disable the
    'warning-is-error' logger for these options. We may wish to change this
    behavior in the future.

    It is not really possible to test this yet as the output wouldn't look
    much different. In addition, the error messages generated are rather
    unhelpful. Both of these can be changed in a future modification.

    Change-Id: Ic6c2dcbe7823dd3fdc71db8dc5afab2d604559e3
    Closes-Bug: #1755783

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/oslo.config 6.1.0 release.

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/nova 18.0.0.0b1 development milestone.

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/554632
Committed: https://git.openstack.org/cgit/openstack/oslo.config/commit/?id=eb6b43ba06698d37e2d8090335e0082f0a6dfdb5
Submitter: Zuul
Branch: master

commit eb6b43ba06698d37e2d8090335e0082f0a6dfdb5
Author: Stephen Finucane <email address hidden>
Date: Tue Mar 20 16:29:07 2018 +0000

    sphinxext: Reporting correct lines for errors

    Previously, we had an issue whereby errors found in the generated source
    would result in the following, rather unhelpful error messages:

      <oslo_config.sphinxext>:1: WARNING: Unexpected indentation.

    Turns out that the 'ViewList.append' function takes a third argument,
    'offset', to indicate where in the source an error is occurring. Start
    using this to improve the quality of the error messages we get from
    poorly formatted options. Given that we don't actually modify the source
    file, it's also necessary to write the output from the directive to an
    intermediate temp file.

    This also fixes the order of imports, given that we're adding new
    imports as we go.

    Change-Id: I6f6796629705926dbed5015f20d47187b77c9c50
    Related-Bug: #1755783

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/552874
Committed: https://git.openstack.org/cgit/openstack/nova/commit/?id=68e6551e85e9283cbff22a22a71c4d7b427079b7
Submitter: Zuul
Branch: master

commit 68e6551e85e9283cbff22a22a71c4d7b427079b7
Author: Stephen Finucane <email address hidden>
Date: Wed Mar 14 10:41:32 2018 +0000

    conf: Correct documentation for '[pci] passthrough_whitelist'

    Literal blocks weren't being rendered as such, causing them to render as
    regular text with smartquotes. This meant people could not copy-paste
    the same config provided. Correct this.

    Change-Id: Ice377939ff7214738419f940e69307ae0a4f0b19
    Related-Bug: #1755783

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/queens
Review: https://review.openstack.org/629869

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/629869
Committed: https://git.openstack.org/cgit/openstack/oslo.config/commit/?id=6056677f35347cd82c12fc9020b02ef142dbe289
Submitter: Zuul
Branch: stable/queens

commit 6056677f35347cd82c12fc9020b02ef142dbe289
Author: Stephen Finucane <email address hidden>
Date: Fri Mar 16 16:53:37 2018 +0000

    sphinxext: Start parsing 'Opt.help' as rST

    Users expect this to be parsed as rST and write their docstrings
    accordingly. This has the potential to introduce warnings for users with
    improperly formatted rST and these warnings can be promoted to errors if
    'sphinx-build' is used with the '-W' option. As a result, we disable the
    'warning-is-error' logger for these options. We may wish to change this
    behavior in the future.

    It is not really possible to test this yet as the output wouldn't look
    much different. In addition, the error messages generated are rather
    unhelpful. Both of these can be changed in a future modification.

    Change-Id: Ic6c2dcbe7823dd3fdc71db8dc5afab2d604559e3
    Closes-Bug: #1755783
    (cherry picked from commit 03ff144f0bf386982d379d18aeb9183146a05fd5)

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/oslo.config 5.2.1 release.