[Discussion] Solutions & Approaches to Reference Integration 'source code linker' not working #357
Description
The Problem
Solve issue that source code linker currently does not work with the reference integration fully.
The scanning source code of external modules (like docs-as-code, baselibs etc.) does not work. Therefore also the linking does not work (source_code_link) for these moduels, due to no template strings being found.
The second issue is that currently the link is build via the 'git hash' of the root directory.
For example if we would find a way to find the links inside the external modules, the link it would then build would still be https://github.com/reference_integration/<current head hash of ref integration>/....
This also seems not as intended as these links obviously wont be found inside of reference integration base repo, and need to link to the actual external module.
Solution => Export The Links Per Module
Creating it's own target that can be called upon by bazel to enable the export of the json file.
There are two approaches to this solution that I have thought up that seem viable in my opinion.
Approach A. Dummy builder for the json
We create a dummy builder that executes the source_code_linker extension and enables it's export.
Benefits:
- Can extend it further and call other things like needs.json builder or other extensions in the future
- Behaves very similar as our current workflow extension as also sphinx during build phase would call it.
- Needs.json already works in this principal, so we already can point to a working example
- [Mabye] Sphinx cache works?
Negatives:
- More complexity
- Have to start sphinx to enable this functionality
Approach B. Seperate script that generates the json
Another approach would be to create a python script that calls upon the different methods needed and in the end ssaves the json file for us.
Benefits:
- [Maybe] Lighter weight, as no sphinx execution
- Easier to understand as no Sphinx Builder wrapper
Negatives:
- [Mabye] Work differently than our source code linker extension due to it executing outside of sphinx
- Have a random script laying around that now also needs testing most likely
- [Maybe] More difficult to have needs.json & this script execute in the same command.
Final Words
Overall I do not have a conclusion yet. For me the solution with the export seems to be the only truly viable option, but which approach I'm currently unsure.
Either approach has pros and cons and I could see both working very well.
In my eyes the Sphinx Builder may make a bit more sense from an argumentation standpoint as the 'needs.json' has set a presedent for that and we just continue the pattern, but it also seems to be worse from a development standpoint.
So now I would like to ask the community for it's feedback.
Is there maybe a solution I missed, or an approach I did not think about?
And which of the two approaches if any do you prefer?
And what do you think is the best place / way to get the correct git hash?