String2Link transformation with Sphinx-Needs

Sphinx-Needs got a new feature that turns option values into links: the string-links feature.

You just set, for example, a GitHub issue ID and get a link to exactly this issue in the final docs.

It only needs to be configured once. After that, every author uses it automatically – for example when writing down a user name, which then becomes a link to the user’s page in Jira.

This makes it really easy to use a docs-as-code solution like Sphinx and reference external data sources.

Example

conf.py

# Create an additional custom option called "github", which takes the issue ID.
needs_extra_options = ['github']

# Turn the number into a link to the issue page of Sphinx-Needs
needs_string_links = {
    # Links to the related GitHub issue
    'github_link': {
        'regex': r'^(?P<value>\w+)$',
        'link_url': 'https://github.com/useblocks/sphinxcontrib-needs/issues/{{value}}',
        'link_name': 'GitHub #{{value}}',
        'options': ['github']
    }
}

The most important parameter is regex. It defines how data is extracted from the string. It supports named capture groups, and the matched values are injected into link_name and link_url, which support Jinja syntax.

In any rst file

.. spec:: Implement the string2link feature
   :id: SPEC_123
   :github: 404

   See the issue above on GitHub for a detailed specification.

Or in MyST Markdown

```{spec} Implement the string2link feature
:id: SPEC_123
:github: 404

See the issue above on GitHub for a detailed specification.
```

Result

All posts