Allow :ref: role to be used with definitions and fields
#10781
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jbms
force-pushed
the
field-and-term-ref-title
branch
3 times, most recently
from
431f682
to
9aa6f43
Compare
jbms
changed the title
jbms
force-pushed
the
field-and-term-ref-title
branch
from
9aa6f43
to
0c87eb8
Compare
|
@AA-Turner Do you think you might have chance to review this? |
|
Please add a CHANGES entry, I will review shortly. A |
Since these nodes have a natural title, there is no reason not to support the :ref: role.
jbms
force-pushed
the
field-and-term-ref-title
branch
from
0c87eb8
to
b78e342
Compare
Done. |
AA-Turner
approved these changes
Sep 6, 2022
AA-Turner
changed the title
:ref: role to be used with definitions and fields
|
Thanks! A |
|
I believe this patch triggers With 5.1.1 our docs built with no warnings: https://github.com/axboe/fio/actions/runs/3106980788/jobs/5034529793 We have Is there a work-around to eliminate the warnings? |
|
@vincentkfu please open a new issue with a minimal reproducer (ideally a single A |
|
I think the best solution would be to restructure your documentation to avoid defining duplicate labels. Even before this patch, you still had duplicate labels, there was just no warning. Potentially you could just suppress the warning, e.g. using the I don't know if it was intentional that Sphinx does not warn on duplicate labels without titles, or if that was just accidental. |
vincentkfu
added a commit
to vincentkfu/fio
that referenced
this pull request
Sep 27, 2022
Sphinx prints warnings when it encounters duplicate labels. In HOWTO.rst are labels for int, irange, and bool. We include HOWTO.rst in both fio_doc.rst and fio_man.rst. Since labels must be unique across all files, Sphinx prints warnings for these labels. For an unknown reason, Sphinx previously did not issue warnings for the duplicate labels mentioned above until 5.2.0. But Sphinx 5.2.1 is now installed for the macOS 11 image in GitHub Actions. So now we see Sphinx warnings when building documentation in GitHub Actions. Our CI treats Sphinx warnings as test failures. So our macOS builds are marked as failures. Resolve this problem by eliminating the separate fio_man.rst file and just building the manpage from the largely equivalent fio_doc.rst. Successful build with 5.1.1: https://github.com/axboe/fio/actions/runs/3106980788/jobs/5034529793 Failed build with 5.2.1: https://github.com/axboe/fio/actions/runs/3129974184/jobs/5079696775 Link: sphinx-doc/sphinx#10781 Link: sphinx-doc/sphinx#10870 Signed-off-by: Vincent Fu <vincent.fu@samsung.com>
axboe
pushed a commit
to axboe/fio
that referenced
this pull request
Sep 27, 2022
Sphinx prints warnings when it encounters duplicate labels. In HOWTO.rst are labels for int, irange, and bool. We include HOWTO.rst in both fio_doc.rst and fio_man.rst. Since labels must be unique across all files, Sphinx prints warnings for these labels. For an unknown reason, Sphinx previously did not issue warnings for the duplicate labels mentioned above until 5.2.0. But Sphinx 5.2.1 is now installed for the macOS 11 image in GitHub Actions. So now we see Sphinx warnings when building documentation in GitHub Actions. Our CI treats Sphinx warnings as test failures. So our macOS builds are marked as failures. Resolve this problem by eliminating the separate fio_man.rst file and just building the manpage from the largely equivalent fio_doc.rst. Successful build with 5.1.1: https://github.com/axboe/fio/actions/runs/3106980788/jobs/5034529793 Failed build with 5.2.1: https://github.com/axboe/fio/actions/runs/3129974184/jobs/5079696775 Link: sphinx-doc/sphinx#10781 Link: sphinx-doc/sphinx#10870 Signed-off-by: Vincent Fu <vincent.fu@samsung.com>
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Feature or Bugfix
Purpose
Since these nodes have a natural title, there is no reason not to
support the :ref: role.