Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(docs): handle fields examples with md_in_html #12465

Merged

Conversation

agilgur5
Copy link
Member

@agilgur5 agilgur5 commented Jan 4, 2024

Fixes #12453

Motivation

  • previously this used a hacky script, hack/parse_examples.go to make markdown work inside of the HTML details element

    • this hack is not run on RTD's build system, and so that meant the markdown ended up rendered as raw text
  • instead of using hacky workarounds, use the md_in_html extension for mkdocs, which will render the markdown inside of the details elements correctly

    • this should also work on RTD seamlessly, as it's not a Go script exclusive to our Makefile

Modifications

  • add a markdown attribute to the details element in hack/docgen.go per https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#markdown-in-html

    • also remove new line that added too much space and is no longer necessary
      • might've been necessary with the hack as I don't remember it creating extra space before
  • remove hack/parse_examples.go and all references to it

  • plus make sure extensions are alphabetized

    • pymdownx.details should be before pymdownx.superfences

Verification

  1. Ran make codegen (make docs/fields.md more specifically) to get the changes to docs/fields.md that are here in this diff
  2. Then ran mkdocs build --strict to replicate the RTD build (i.e. not make docs)
  3. Then open site/fields/index.html and verified the examples worked correctly as in below screenshot:

Before:
Screenshot 2024-01-03 at 11 19 35 PM

After:
Screenshot 2024-01-04 at 4 37 39 PM

Still works properly inside of GH Markdown as well -- see rendered MD on this PR

- previously this used a hacky script, `hack/parse_examples.go` to make markdown work inside of the HTML `details` element
  - this hack is not run on RTD's build system, and so that meant the markdown ended up rendered as raw text

- instead of using hacky workarounds, use the `md_in_html` extension for `mkdocs`, which will render the markdown inside of the `details` elements correctly
  - just need to add a `markdown` attribute to the `details` element per https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#markdown-in-html
  - this should also work on RTD seamlessly, as it's not a Go script exclusive to our `Makefile`

- also remove new line that added too much space and is no longer necessary
  - might've been necessary with the hack as I don't remember it creating extra space before

- also make sure extensions are alphabetized
  - `pymdownx.details` should be before `pymdownx.superfences`

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
@agilgur5 agilgur5 added area/docs Incorrect, missing, or mistakes in docs area/build Build or GithubAction/CI issues labels Jan 4, 2024
@agilgur5 agilgur5 requested a review from jmeridth January 4, 2024 22:00
Copy link
Member

@jmeridth jmeridth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@agilgur5 agilgur5 added the prioritized-review For members of the Sustainability Effort label Jan 5, 2024
@terrytangyuan terrytangyuan self-assigned this Jan 5, 2024
@terrytangyuan terrytangyuan merged commit bcf5672 into argoproj:main Jan 5, 2024
31 checks passed
@agilgur5 agilgur5 deleted the fix-docs-fields-examples-markdown branch January 5, 2024 18:32
jmeridth added a commit to jmeridth/argo-workflows that referenced this pull request Jan 5, 2024
Includes fixes from argoproj#12464, argoproj#12466, argoproj#12465 - all authored by @agilgur5

Includes files list from argoproj#12414 description

Signed-off-by: jmeridth <jmeridth@gmail.com>
Co-authored-by: Anton Gilgur <agilgur5@gmail.com>
jmeridth added a commit to jmeridth/argo-workflows that referenced this pull request Jan 5, 2024
Includes fixes from argoproj#12464, argoproj#12466, argoproj#12465 - all authored by @agilgur5

Includes files list from argoproj#12414 description

Signed-off-by: jmeridth <jmeridth@gmail.com>
Co-authored-by: Anton Gilgur <agilgur5@gmail.com>
jmeridth added a commit to jmeridth/argo-workflows that referenced this pull request Jan 5, 2024
Includes fixes from argoproj#12464, argoproj#12466, argoproj#12465 - all authored by @agilgur5

Includes files list from argoproj#12414 description

Signed-off-by: jmeridth <jmeridth@gmail.com>
Co-authored-by: Anton Gilgur <agilgur5@gmail.com>
isubasinghe pushed a commit to isubasinghe/argo-workflows that referenced this pull request Feb 27, 2024
Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
isubasinghe pushed a commit to isubasinghe/argo-workflows that referenced this pull request Feb 27, 2024
Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
isubasinghe pushed a commit to isubasinghe/argo-workflows that referenced this pull request Feb 27, 2024
Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
isubasinghe pushed a commit to isubasinghe/argo-workflows that referenced this pull request Feb 28, 2024
Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
Signed-off-by: Isitha Subasinghe <isubasinghe@student.unimelb.edu.au>
@agilgur5 agilgur5 added this to the v3.5.x patches milestone Apr 9, 2024
isubasinghe pushed a commit to isubasinghe/argo-workflows that referenced this pull request May 6, 2024
Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/build Build or GithubAction/CI issues area/docs Incorrect, missing, or mistakes in docs prioritized-review For members of the Sustainability Effort
Projects
None yet
Development

Successfully merging this pull request may close these issues.

RTD Docs: Fields Reference example links are broken
3 participants