Feature: :srcref:
can deep-link to specific source lines
#188
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This extends the
:srcref:
rST role with deep-links into specific source lines. This feature was explicitly requested here. Additionally, I integrated the:srcref:
extension @FAlbertDev added in #186.As an example, I deep-linked a source location in the Kyber crypto doc. The result (in HTML output) looks like that:
... and links to: https://github.com/randombit/botan/blob/7f15ce7b39d6bd34dda9af4d2cb08a6e18c64c01/src/lib/pubkey/kyber/kyber_common/kyber.cpp#L1042
Usage
In reStructuredText the
:srcref:
annotation understands the following::srcref:`src/lib/hash/sha1/sha1.cpp`
sha1.cpp
on GitHub, using the full path as link text, namely "src/lib/hash/sha1/sha1.cpp".:srcref:`src/lib/pubkey/xmss/`
xmss
directory on GitHub, using the full path as link text, namely "src/lib/pubkey/xmss".:srcref:`XMSS <src/lib/pubkey/xmss/>`
xmss
directory, using "XMSS" as link text.:srcref:`\[src/lib/hash]/sha1/sha1.cpp`
sha1.cpp
, using an elided path as link text, namely: ".../sha1/sha1.cpp".:srcref:`TLS 1.3 key export <src/lib/tls/tls13/tls_cipher_state.cpp:400|CipherState::export_key>`
tls_cipher_state.cpp
line 400, using "TLS 1.3 key export" as link text. The stringCipherState::export_key
must be found in this line, so that a Continuous Integration job can check that the deep-link didn't get out of sync with the upstream source code.:srcref:`\[src/lib/tls/tls13]/tls_cipher_state.cpp:400|CipherState::export_key>`
tls_cipher_state.cpp
line 400, using an elided path as link text, namely: "...tls_cipher_state.cpp:400". The search string works the same as explained above.