-
Notifications
You must be signed in to change notification settings - Fork 23.7k
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
added documentation for R() #69832
added documentation for R() #69832
Changes from 3 commits
aba132c
1062294
b60f264
00b33a0
92e1c40
a374f20
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -273,15 +273,18 @@ Linking within module documentation | |
|
||
You can link from your module documentation to other module docs, other resources on docs.ansible.com, and resources elsewhere on the internet. The correct formats for these links are: | ||
|
||
* ``L()`` for Links with a heading. For example: ``See L(IOS Platform Options guide,../network/user_guide/platform_ios.html).`` | ||
* ``L()`` for links with a heading. For example: ``See L(Ansible Tower,https://www.ansible.com/products/tower).`` As of Ansible 2.10, do not use ``L()`` for relative links to other Ansible documentation. Use ``R()`` instead. | ||
* ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/tower) for an overview.`` | ||
* ``R()`` for cross-references with a heading (added in Ansible 2.10). For example: ``See R(Cisco IOS Platform Guide,ios_platform_options).`` Use the RST anchor for the cross-reference. | ||
* ``I()`` for option names. For example: ``Required if I(state=present).`` | ||
* ``C()`` for files and option values. For example: ``If not set the environment variable C(ACME_PASSWORD) will be used.`` | ||
* ``M()`` for module names. For example: ``See also M(win_copy) or M(win_template).`` | ||
|
||
.. note:: | ||
|
||
For modules in a collection, you can only use ``L()`` and ``M()`` for content within that collection. Use ``U()`` to refer to content in a different collection. | ||
For modules in a collection, you can only use ``L()`` and ``M()`` for content within that collection. Use ``U()`` to refer to content in a different collection, or ``R()`` for cross-references to other Ansible documentation, based on the anchor for the page or section of the ``.rst`` file. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. A few notes about this section
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm confused now.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Okay so U() is for raw links so to speak (no title) and L() includes a title for the link. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Discussed in #ansible-doc and we will mention intersphinx w/ a link to the intersphinx docs for how to get M() and R() working on a separate docsite. |
||
|
||
|
||
|
||
.. note:: | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So care needed if backporting docs fixes from devel to
stable-2.9
?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes. This is predominantly driven by collections, but it's safer to just start using R() imo. @abadger can correct me if I'm confused on that point :-)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, except that
R()
inside of options and returndocs won't form a link. At the moment, the tables for options and returns are created using raw-html embedded in rst. Because of that, sphinx doesn't get a chance to process them and thus can't turn it into a linkThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Isn't the above true for all links? I don't think L() or U() would create a link within the options or return docs either. Would they?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
L()
andU()
should form links in the options and return docs. Those take a URL (relative or absolute) and therefore it has all the needed information to make a link in html without having to be processed by sphinx. Here's an example which should show the difference between those two andR()/M()
:Here's what could be in the DOCUMENTATION variable:
Here's an approximation of the jinja template:
And here's what combining those two should generate in the rst file:
The difference between
U() / L()
andM() / R()
is that the former have enough information to generate an<a href=URL>
on their own. The latter only have enough information to generate a sphinx:ref:
. The sphinx ref would have to be processed by sphinx (ie: outside of a.. raw:: html
block in the rst) in order to turn into a link.