String2Link transformation with Sphinx-Needs#
Sphinx-Needs got a new cool feature to easily create links of a given string for options. The string-links feature.
This allows to just set e.g. a github issue id and get a link to exactly this issue in the final docs.
It only needs to be configured once and then each author will use it automatically, if he or she writes down e.g. a username, which then gets transformed to the user page on JIRA.
This makes it really easy to use a docs-as-code solution like sphinx and reference external data sources.
Example#
conf.py
# Lets create an additional custom option, called "github", which shall take the issue id.
needs_extra_options = ['github']
# Now some configuration, so that the number gets transformed to a link to the isse 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. There you can define how data shall be extracted from the string.
It’s supporting named
capture groups
and the matched values get injected into link_name and link_url,
which support Jinja syntax.
Inside any rst/md file
.. spec:: Implement the string2linkfeature
:id: SPEC_123
:github: 404
See above issue on github for a detailed specification
```{spec} Implement the string2linkfeature
:id: SPEC_123
:github: 404
See above issue on github for a detailed specification
```
Result
See above issue on github for a detailed specification |
Sphinx-Needs String2Link feature details |
Comments
comments powered by Disqus