1.3.4. Linking

• Link to a website (external of document)

  1. See fill URL method

     • Syntax: `<https://www.sphinx-doc.org/>`_

     • Rendered: https://www.sphinx-doc.org/

  2. Use a Label and hide URL method

     • Syntax: `Sphinx <https://www.sphinx-doc.org/>`_

     • Rendered: Sphinx

• You can also use the .. seealso: {link}

  • Syntax:

    .. seealso:: https://www.sphinx-doc.org/

  • Rendered:

    See also

    https://www.sphinx-doc.org/

• Link to a reST Anchor (internal of document from /source) that generates a hyperlink to anchor with a title (title can be different than section). Remeber to link to other documents outside of /source use links file to create a link to their /source in your document /source.

Note

Using :ref: is advised over standard reStructuredText links to sections (like `Section title`_) because it works across files, when section headings are changed, and for all builders that support cross-references.

Note

When linking to a section title, put the link above the title with a blank line for separation.

• Syntax

  • Creating Link Anchor (Above title on doc_structure.rst):

    .. _building_toctable:

  • Linking to Anchor and creating title for link:

    :ref:`Building a TOCtable<building_toctable>`

• Rendered: :

  • Creating Link Anchor (Below title on doc_structure.rst):

  • Linking to Anchor:

    Building a TOCtable

Note

You can also use :numref:`<Figure anchor>` to provide just a Figure or Table #.# link

• Linking to files for download in HTML builds

  When you use this role, the referenced file is automatically marked for inclusion in the output when building (obviously, for HTML output only using .. only:: builder_html). All downloadable files are put into the _downloads subdirectory of the output directory; duplicate filenames are handled.

  The given filename is usually relative to the directory the current source file is contained in, but if it absolute (starting with /), it is taken as relative to the top source directory.

  The example.py file will be copied to the output directory, and a suitable link generated to it.

  Not to show unavailable download links, you should wrap whole paragraphs that have this role for html only builds:

  • Syntax:

    .. only:: html
    
        See ``:download:`Example Script Download Link </scripts/examples/colors.json>```
    

  • Rendered: No output in latexpdf build

    See Example Script Download Link