Links

Building links is easy, right up to the point where they don’t get built. And then you may want to hurl something. Including yourself or possibly your lunch.

ICG Usage

Here is an attempt to strip the large subject of links down to a simplest possible form that is consistent with usage you’ll see in Itasca docs:

• always use the :name: option in a directive to set a target, if available.
• only use a label to set a target (i.e., .. _label:) when :name: is not available (either you aren’t in a directive, or you are in one of the very few directives that does not use :name: — namely the inclusion directives)
• always make hyperlinks with label + target address, like this:
  :ref:`link includes label <this_is_the_target>`.
  Though valid, do not build links like this:
  :ref:`this_is_the_target` .

This should cover the vast majority of links needed. Maybe that’s good enough, in which case please also quickly review ICG Target Names below (and then you’re done).

It may be that you need to build some other kind of link or have a special case, so…

Link Cookbook

Need to do something else? Here is a “how to” on a bunch of different other kind of links that diverge from the recipe above.

Link to a Command (+ Keywords!) – The :cmd: Role

The above gets you this link: :cmd:`model.new`.

The above gets you this link: model new.

The :cmd: role being used here was built by Itasca (not to be found in docs on Docutils/Sphinx). It is quite simple to use. Put a “.” anywhere in a command where there is normally a space when building links.

You can also add keywords (again, with “.”) to any length.

See where this takes you: geometry assign-groups structure liner.

See where this takes you: :cmd:`geometry.assign-groups.structure.liner`.

As long as the ordering of the command words/keywords is correct, you can get to any spot in a command doc using the above technique.

Link to a FISH Function – The :func: Role

Functions are, if anything, easier: :func:`math.cos`.

Functions are, if anything, easier: math.cos.

Similar to commands. Also a customization from ICG, so again it isn’t documented in Docutils/Sphinx. FISH function names come with dots and don’t have keywords, so in all cases you just put the function name in the :func: role and you’re done.

Link to a Web Site

Go to the `PFC Section <https://www.itascacg.com/software/pfc>`_ of Itasca's
web site or you may be ok with just showing the URL in your text, like this
https://www.itascacg.com/software/pfc.

Go to the PFC Section of Itasca’s web site or you may be ok with just showing the URL in your text, like this https://www.itascacg.com/software/pfc.

Well formed URLs (the latter case) are automatically converted to hyperlinks, no markup required. However, if the address itself is not consequential, it is preferable to fold links into the surrounding text as in the former case ( `label <url>`_ ). Don’t forget the underscore at the end on those!

Links for Footnotes & Citations

These links are built automatically when a footnote or citation is constructed; see the topics on those for instructions.

Links that Use the Code-Text Font

Sometimes you refer to commands as a group (e.g., the
|c| :ref:`geometry <geom_command>` commands), in which case you'll want
your link label to use the standard code-text font.

Sometimes you refer to commands as a group (e.g., the c geometry commands), in which case you’ll want your link label to use the standard code-text font.

This is built just like a regular link would be, except the substitution |c| put in front of the link causes the link label to be rendered in the code-text font.

Links that are Italicized

A link that takes users to documentation on the
|i| :ref:`Control Panel <controlpanel>` should be italicized.

Named objects in the UI should be italicized, as should topic titles. Put the substitution |i| in front of a regular link to cause its label text to be italicized.

ICG Target Names

• use a prefix
• avoid evidently “common” constructions (fig1, eq1, table, intro, etc.)

It is an obvious anomaly to have duplicate targets defined in the doc set, however, there is currently no way to verify, a priori, that a target you’re building is truly unique. And the doc set is massive, with thousands of defined targets, which is not to mention all the other auto-magically created targets (all commands, FISH, and the implicit targets that Sphinx creates). Some target duplication is inevitable.

For this reason, it is a good practice (though not required) to establish a “prefix” within a document that can be used on all that document’s internal targets. Examples (example applications, verification problems, etc.) are good candidates for the prefix treatment.

Just put the prefix string in a comment at the top of a document, above the title (and any target that appears above the title). It might look like this:

.. prefix: radcyl

.. _radialcylinder_example::

Example of a Radial Cylinder Mesh in 3DEC
#########################################

Having established “radcyl” as the prefix, put those characters in front of all targets in the document: “radcyl_figure_problem”, “radcyl_quadratic_equation”, “radcyl_table_props”, etc.

Yes, the prefix is no more immune to the uniqueness conundrum than un-prefixed targets are, but duplication is improbable if not impossible. Also, if followed uniformly within a document, a duplicated prefix will be corrected easily via search/replace. If prefix duplication ever does become a big issue, we could standardize the prefix declaration to make all of them globally find-able via “find in files” operation.