Aus Text wird ein Link: String2Link mit Sphinx-Needs

Dieser Beitrag erschien ursprünglich auf Englisch. Zum Original

Sphinx-Needs hat ein neues Feature, das Optionswerte in Links verwandelt: das String-Links-Feature.

Du trägst zum Beispiel nur die ID eines GitHub-Issues ein und bekommst in der fertigen Doku einen Link genau auf dieses Issue.

Konfigurieren musst du das nur einmal. Danach nutzt es jeder automatisch – etwa, wenn jemand einen Nutzernamen hinschreibt, der dann auf die Profilseite in Jira verlinkt.

So lässt sich mit einer Docs-as-Code-Lösung wie Sphinx sehr einfach auf externe Datenquellen verweisen.

Beispiel

conf.py

# Eine zusätzliche Option "github" anlegen, die die Issue-ID aufnimmt.
needs_extra_options = ['github']

# Aus der Nummer einen Link auf die Issue-Seite von Sphinx-Needs machen
needs_string_links = {
    # Link auf das passende 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']
    }
}

Der wichtigste Parameter ist regex. Er legt fest, wie die Daten aus dem Text gelesen werden. Er unterstützt benannte Capture Groups; die gefundenen Werte landen in link_name und link_url, die Jinja-Syntax verstehen.

In einer beliebigen rst-Datei

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

   See the issue above on GitHub for a detailed specification.

Oder in MyST Markdown

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

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

Ergebnis

Alle Beiträge