chore: Reference Github code in Docusaurus

[geido]

SUMMARY

This is a POC for referencing Github code in Docusaurus.

AFTER

POC.Github.code.ref._.Superset.mp4

ADDITIONAL INFORMATION

• Has associated issue:
• Required feature flags:
• Changes UI
• Includes DB Migration (follow approval process in SIP-59)
  • Migration is atomic, supports rollback & is backwards-compatible
  • Confirm DB migration upgrade and downgrade tested
  • Runtime estimates and downtime expectations provided
• Introduces new feature or API
• Removes existing feature or API

[ad-m]

I like the direction, but I am afraid about the maintenance of that solution in long term. We have a hard-coded commit ID (or git tag) and a hard-coded line number. This can be easily outdated:

• the example will be updated and the commit IT will not be updated to point to the new code,
• the reference will be updated with the new code, but the lines will not be changed, e.g. extended with an additional enter added.

As for the first case, we may use the version identifier (git tag) instead of commit in the future. However, then the second case is then even more likely.

To reduce this case scenario Apache Airflow uses comments in the referenced file ( https://github.com/apache/airflow/blob/main/docs/apache-airflow/tutorial_taskflow_api.rst ), predicable comment structure (tags eg. for examples is added before this is required in the documentation). It allows also check that references on CI.

[geido]

I like the direction, but I am afraid about the maintenance of that solution in long term. We have a hard-coded commit ID (or git tag) and a hard-coded line number. This can be easily outdated:

• the example will be updated and the commit IT will not be updated to point to the new code,
• the reference will be updated with the new code, but the lines will not be changed, e.g. extended with an additional enter added.

As for the first case, we may use the version identifier (git tag) instead of commit in the future. However, then the second case is then even more likely.

To reduce this case scenario Apache Airflow uses comments in the referenced file ( https://github.com/apache/airflow/blob/main/docs/apache-airflow/tutorial_taskflow_api.rst ), predicable comment structure (tags eg. for examples is added before this is required in the documentation). It allows also check that references on CI.

Hey @ad-m you are perfectly right and we also share these concerns. However, for the time being, we are happy with this solution as the code references that we are looking to add do not change very often. We definitely would like to think of longer-term solutions and the Airflow solution seems well structured. I am pinging @villebro who also has some ideas on this topic.

[geido]

As the POC was successful I am removing the POC file and moving this PR to mergeable