best way to list external references

[Ed H]

Hi,

I am just learning Sphinx and would appreciate guidance on the best way to insert links to external records. Specifically wanting to write product documentation in Sphinx and link to corresponding API documentation, as well as related specification/requirement records. I'm imagining something along the lines of:

Example feature

--------------------------

This feature does xyz. You can use it by doing abc.

.. api :: example-feature, list-example-features

.. req :: R-123, R-456

Both directives would insert a block that look similar to the "seealso" directive, something like:

API Reference 

     example-feature, list-example-features

Requirements

     R-123, R-456

Hyperlinked to the external reference, which has a fixed format derived from the name, e.g. 

example-feature would link to https://api.example.com/example-feature

R-123 would link to https://issue-tracker.example.com/R-123

I followed the HelloWorld custom directive tutorial, but am not sure where to go from there, or if that's even the best starting point. In any case, I thought I should ask for help from the experts for any advice you may have, which would be very much appreciated!

Thank you,

Ed

[Martin Bless]

Hello,

> I am just learning Sphinx and would appreciate guidance on the best
> way to insert links to external records. Specifically wanting to write
> product documentation in Sphinx and link to corresponding API
> documentation,

what we did for a while in TYPO3 documentation (https://docs.typo3.org) was:

- use a script to create an 'objects.inv' file for tha API urls

- then use normal intersphinx crossreferencing.

Follow these explanations:
https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

This works totally fine. However we gave up on this as our API was
changing too much from version to version and we didn't need that many
links.

Martin Bless

[Ed H]

Hi Martin,

Thank you for the suggestion. I added the intersphinx extension, created an jira-objects.txt' from scratch following the sphobjinv guide, compressed to jira-objects.inv using the sphobjinv converter.... However I haven't been able to understand the format for either objects.inv or cross references. Perhaps someone can see my error...

jira-objects.txt (compressed to jira-objects.inv)

# Sphinx inventory version 2

# Project: JIRA

# Version: 

# The remainder of this file is compressed using zlib.

ABC-1234 std:label 1 #$ This is an example JIRA ticket reference. 

conf.py includes this option:

intersphinx_mapping = {'jira': ('https://example.atlassian.net/browse', 'jira-objects.inv')}

Within a page I then tried a number of ways to reference ABC-1234 with no luck.

Example 1:

Reference to :ref:`ABC-1234`.

Produces:

Reference to ABC-1234.

(No link, styling or display name shown.)

Example 2: 

Reference to :label:`ABC-1234`..

Produces:

Reference to :label:`ABC-1234` testing.

With a broken link to #id1.

I was not sure what to put for the domain, role or URI.  I am hoping for output like the following:

Reference to ABC-1234.

and

Reference to ABC-1234 This is an example JIRA ticket reference..

The link is simply the the name/id appended to the base URL that I specified in the conf.py intersphinx_mapping option, i.e. https://example.atlassian.com/browse/ABC-1234. 

Any additional help would be greatly appreciated!

Thanks,

Ed

[Martin Bless]

Hello Ed,

using the sphobjinv converter....

ah, interesting, I'll take a look.

Have you seen https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#showing-all-links-of-an-intersphinx-mapping-file?

You could run that for your file and, let's say, https://docs.python.org/3/objects.inv and then compare the two.

--

Martin Bless

[Ed H]

Hi Martin, thanks, that did give me some clues, and I also found the ReadTheDocs Intersphinx documentation helpful.

I got a basic prototype working with std:doc and a simple $ for the URI in the jira.objects.inv: 

ABC-1234 std:doc -1 $ This is an example JIRA ticket reference. 

Then the following reference:

Reference to :doc:`jira:ABC-1234`.

Generates the desired output: 

Reference to This is an example JIRA ticket reference..

I'll mention that I also stumbled upon a few other projects that address this in other ways:

https://sphinxcontrib-needs.readthedocs.io/

https://sphinx-test-reports.readthedocs.io/en/latest/

https://github.com/melexis/jira-traceability

https://github.com/sphinx-contrib/requirements

Thanks much for your tips!

Ed

[Martin Bless]

Hi Ed,

① thanks for pointing me to that `sphobjinv` tool. Very helpful!

② I used it to look into one of our `objects.inv` files. A drastically shortened version looks like this:

# Sphinx inventory version 2

# Project: TYPO3 Explained
# Version: 11.0 (development)

# The remainder of this file is compressed using zlib.

About std:doc -1 About.html About This Manual
ApiOverview/Index std:doc -1 ApiOverview/Index.html API Overview
be-user std:label -1 ApiOverview/BackendUserObject/Index.html#$ Backend User Object
be-user-admin std:label -1 ApiOverview/BackendUserObject/Index.html#$ Is “admin”?

Then, in reStructuredText, we can write
   :doc:`About`

to create a link to the file https://.../About.html

and you can write
   :ref:`be-user`

to create a link to the bookmark https://.../ApiOverview/BackendUserObject/Index.html#be-user

I know this just from experience and I'm still looking myself for documentation why 'ref' is used for 'std:label' and 'doc' for 'std:doc'.

BTW, these are the real links:
https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/About.html#about
https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/ApiOverview/BackendUserObject/Index.html#be-user

③ FYI: About six years ago I created a Sphinx-extension that we are still using. I has a single directive:

.. ref-targets-list::

that will produce the content you see here: https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/Targets.html

Editors can consult that page to see what crossreferencing targets are available.

See https://github.com/TYPO3-Documentation/sphinxcontrib.t3targets and https://pypi.org/project/t3targets/

-- 

Martin Bless

[Martin Bless]

Hello Ed,

now, looking again at your post:

jira-objects.txt (compressed to jira-objects.inv)

# Sphinx inventory version 2

# Project: JIRA

# Version: 

# The remainder of this file is compressed using zlib.

ABC-1234 std:label 1 #$ This is an example JIRA ticket reference. 

conf.py includes this option:

intersphinx_mapping = {'jira': ('https://example.atlassian.net/browse', 'jira-objects.inv')}

Within a page I then tried a number of ways to reference ABC-1234 with no luck.

Example 1:

Reference to :ref:`ABC-1234`.

You almost got it right. What you have to write to create the link:

① :ref:`...`   <- this is the correct textrole.
② :ref:`ABC-123`  <- The label is correct. Would work if the label was defined in the same project
③ :ref:`jira:ABC-123` <- This will really work. Prefix the label with 'jira:', because you chose 'jira' in the Intersphinx mapping

Line ③ will have 'This is an example JIRA tecket reference" as linktext.

④ :ref:`Feature 123 <jira:ABC-123>` will work and have linktext 'Feature 123'

Note:

- case of the label doesn't matter
- case of the prefix ('jira') may matter - I don't know by heart
- Don't forget one or more blanks before the '<' in ④.

Let me know if that works!

--
Martin Bless