RTD Docs: Fields Reference example links are broken

[agilgur5]

Pre-requisites

• I have double-checked my configuration
• I can confirm the issues exists when I tested with :latest
• I'd like to contribute the fix myself (see contributing guide)

What happened/what you expected to happen?

In the Fields Reference on RTD at https://argo-workflows.readthedocs.io/en/latest/fields/ all of the "Examples" dropdowns are currently not rendering markdown properly and are displaying raw text. See below screenshot:

As a result the list is not displaying correctly and you can't directly click the links either.

I'm actually not yet sure why this is happening, which is why I filed an issue instead of a PR currently

Regression from #12360, although again not entirely sure how/why, potentially due to mkdocs dep version changes?

Version

https://argo-workflows.readthedocs.io/en/latest/fields/

Paste a small workflow that reproduces the issue. We must be able to run the workflow; don't enter a workflows that uses private images.

n/a this is specific to the docs

Logs from the workflow controller

n/a this is specific to the docs

Logs from in your workflow's wait container

n/a this is specific to the docs

[jmeridth]

It's the <details> sections for the examples (code). I know that is a GitHub markdown thing but don't know if it is through another extension in mkdocs. Definitely a plugin/extension that went missing. I'm looking into this.

[jmeridth]

Possibly related? squidfunk/mkdocs-material#4084

[agilgur5]

We do use pymdownx.details which is mentioned in squidfunk/mkdocs-material#4084 (comment). It's included as part of mkdocs-material.

Although the code you linked above (which is generated by hack/docgen.go) actually doesn't use the syntax from pymdownx.details... 🤔
I wonder if potentially it just happened to work in one version and then broke as it wasn't intended to be used like that anyway.

We'd want to use the md_in_html extension then and add the markdown attribute to all the details blocks. I do want to investigate a bit more before implementing that though

[agilgur5]

I figured it out.

make docs will create the correct docs, but mkdocs build won't. Specifically there's a line in the Makefile:

# fix the fields.md document
go run -tags fields ./hack parseexamples

That will end up running hack/parse_examples.go which modifies the rendered output from mkdocs.

And that code is not currently running in RTD's build.

It probably makes sense to have this work with a mkdocs extension instead of a custom hack, so I'm going to go ahead and modify it as such.

[jmeridth]

@agilgur5 nice catch. agreed re: not using a hack. Sorry I missed this.

[agilgur5]

I missed it during review too; I suppose that's one of the problem with hacks, they can be missed easily if you don't know about them 😅

But good thing we are now removing a handful of hacks with these updates!