Documentation: make the GitHub URLs depend on the current branch

[aalemayhu]

Using git to retrieve the current branch and then storing it in the
epilogue where it's globally available. This can later be moved should
there be a conflicts on the names. Since the base URL is a variable now
and used in the blocks, had to change to using a parsed-literal so
they are rendered. One downside to this is that we no longer get the
consistent frame around the text like the code blocks.

Closes: #1755 (Make URLs version specific to provide backwards compatibility in docs)
Signed-off-by: Alexander Alemayhu alexander@alemayhu.com

[tgraf]

@scanf Did you generate this locally with sphinx to verify it works?

[aalemayhu]

@tgraf Are you seeing anything wrong with the output? Did not see any issues. Was testing it on a different server, rendered below

https://alemayhu.com/cilium-staging/gettingstarted.html#getting-started-using-kubernetes

https://alemayhu.com/c.pdf

[aalemayhu]

Tested locally now and works for local branches (X), but not for remote branches (origin/X). So git is returning HEAD for those, but this shouldn't matter assuming the branches are locally checked out on read the docs.

[tgraf]

@tgraf Are you seeing anything wrong with the output? Did not see any issues. Was testing it on a different server, rendered below

The only minor issue I can see is that the preformatted boxes are now rendered differently in my browser. The boxes with the links are rendered in a bigger font. Not an issue though.

[aalemayhu]

Noticed the font and frame mismatch as well. So we are changing the default because the code directive does not parse the text and is mainly offering syntax highlighting. Not familiar with the customization options, but could take a look if you want. Maybe sphinx has some way of creating own directives that inherit from others. If that's the case we could try to inherit from parsed-literal and then try to provide a separate CSS file for the font size and border with similar values as the code directive.

[tgraf]

Noticed the font and frame mismatch as well. So we are changing the default because the code directive does not parse the text and is mainly offering syntax highlighting. Not familiar with the customization options, but could take a look if you want. Maybe sphinx has some way of creating own directives that inherit from others. If that's the case we could try to inherit from parsed-literal and then try to provide a separate CSS file for the font size and border with similar values as the code directive.

I think this is fine. File a github issue with the doc tag so we don't forget about this. I think eventually we want to tackle things like these.

[aanm]

@joestringer The tests failed. Do you think it is related with the L7 changes we found a week ago?

@scanf Can you rebase?

[joestringer]

@aanm This failure looks the same as #1362.

[aalemayhu]

@aanm Rebased

[aanm]

Can you add the link to the ConfigMap?

[aalemayhu]

Can you add the link to the ConfigMap?

Added link to the kubernetes docs.

[aalemayhu]

Need to add this comment, so it's removed from review queue. Please ignore.