added documentation for R()

[samccann]

SUMMARY

A recent PR added support for R() within module docstrings. This works much like the sphinx :ref: but requires both the link text and the rst label.

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

docs.ansible.com

ADDITIONAL INFORMATION

[gundalow]

As of Ansible 2.10, do not use L() for relative links to other Ansible documentation. Use R() instead.

So care needed if backporting docs fixes from devel to stable-2.9?

[samccann]

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 :-)

[abadger]

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 link

[acozine]

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?

[abadger]

L() and U() 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 and R()/M():

Here's what could be in the DOCUMENTATION variable:

options:
    - name: verify_certs
      description:
         - Verify the L(certificate, https://en.wikipedia.org/wiki/Public_key_certificate) of the server when True.
         - Use M(community.crypto.openssl_cert) to manage that on your server

Here's an approximation of the jinja template:

.. raw:: html
   <table><tr>
  <td>{% for line in option['description'] %}
    @{line | html_ify}@
  {% endfor %}</td>
  </tr></table>

And here's what combining those two should generate in the rst file:

.. raw:: html
   <table><tr>
   <td>
      Verify the <a href="https://en.wikipedia.org/wiki/Public_key_certificate">certificate</a> of the server when True.
      Use <span class="module">community.crypto.openssl_cert</span> to manage that on your server
  </td>
  </tr></table>

The difference between U() / L() and M() / 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.

[abadger]

A few notes about this section

• L() can be used for content outside the collection. So maybe that part is better phrased as:

  you should only use relative links with L() and U() if the content lives within the collection.

• relative links can work outside of the collection, but only if you know the directory structure outside of the collection. In particular, that means that a relative link that works with docs-pipeline probably won't work on the collection maintainer's website and vice versa.
• M() and R() should work inside of a collection always. Pointing outside of a collection, they can work in the docs pipeline. They may be able to work on a collection maintainer's website if they have intersphinx setup appropriately and there's no conflicts in the ref names.

[samccann]

I'm confused now.

1. I thought U() was only for full urls, not relative links? At least that is the example we use.

2. For L() as a relative link, is that to the collection docs folder? to..??? not sure what a relative link within a collection looks like.

3. For relative links outside a collection, that just seems problematic and I suggest we don't advertise it.

4. M() and R() - @acozine - I'm of two minds here - it's a good point that people building their own docsite would need to know they need intersphinx to get them working, but I'm not sure we are/should be in the business of documenting how someone builds their own docsite from module content. I could just add a phrase after that last sentence to say something like "These cross-references to other Ansible documentation work based on the intersphinx extention'. ?

[abadger]

1. The only difference between 'U()' and 'L()' that I can see in the code is whether to include the bare link or to include a heading. for example:

   <!--  U("../../collections/index.html") turns into -->
   <a href="../../collections/index.html">../../collections/index.html</a>
   
   <!-- L(List of collections, "../../collections/index.html") turns into -->
   <a href="../../collections/index.html">List of collections</a>

   (absolute URLS will work for both of those as well)
2. Relative links are relative to the html page. So, if I am working on documentation in the yum module from ansible-base, I could refer to the apt module's documentation via: L(The apt module,apt_module.html) because the apt module is also in ansible-base and will therefore be placed in the same directory. If I am working on the yum module docs and i wanted to reference something in another collection, I could use L(Ansible documentation,../../../index.html) to reference the toplevel index page of the docs.ansible.com website. (But on a collection owner's website, that might not be the correct location for what they want to reference).
3. Yep. Agreed
4. I know you're really asking acozine but I just wanted to say I agree, something that says this is possible but points them elsewhere to get the details seems like a good compromise. Although, we may want people to know that if they're only developing for publication on docs.ansible.com, they don't have to know about intersphinx?

[samccann]

Okay so U() is for raw links so to speak (no title) and L() includes a title for the link.
Relative linking needs more explanation, and I think we should limit it to -use docs.ansible.com relative links only if you are in ansible base. Use relative links in your collection only to your own collection. Use L() or U() to link from your collection to docs.ansible.com pages outside your collection.

[samccann]

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.