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.

Sign up for GitHub

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

Jump to bottom

MathJax does not produce results #2175

Closed
wyskoj opened this issue Oct 4, 2021 · 6 comments · Fixed by #2342
Closed

MathJax does not produce results #2175

wyskoj opened this issue Oct 4, 2021 · 6 comments · Fixed by #2342
Labels
bug

Comments

@wyskoj
Copy link
Contributor

wyskoj commented Oct 4, 2021 •
edited
Loading

Describe the bug
I am attempting to use the MathJax plugin to add math support for my documentation. Whenever I add the @usesMathJax annotation to a KDoc, the documentation fails to render.

Expected behaviour
The documentation to appear with correct math rendering.

Screenshots
Given the following class and method,

/**
 * An example class.
 */
class Example {
    /**
     * @usesMathjax
     * An example method.
     * \(a^2 + b^2 = c^2\)
     */
    fun foo() = println("Hello, world.")
}

this is what's rendered:
image

A similar render appears with classic Javadoc (nothing appears for the documentation of the method).

To Reproduce

  • Create a piece of documentation and apply the @usesMathJax annotation
  • Include valid MathJax in the documentation
  • Run dokkaHtml (or dokkaJavadoc)
  • Observe the output

Dokka configuration

plugins {
    id("org.jetbrains.kotlin.jvm") version "1.5.31"
    id("org.jetbrains.dokka") version "1.5.30"
    java
    idea
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.jetbrains.kotlin:kotlin-stdlib")
    implementation("org.jetbrains.dokka:mathjax-plugin:1.5.31")
}

Installation

  • Operating system: Same results on both Windows 11 and Ubuntu 20.04
  • Build tool: Gradle v7.1
  • Dokka version: 1.5.30

Additional context
I found little documentation on how to use this plugin, so it could be simply I'm using it all wrong. If that's the case, how can I appropriately use this plugin?

Are you willing to provide a PR?
Sure.
@wyskoj wyskoj added the bug label Oct 4, 2021
@wyskoj
Copy link
Contributor Author

wyskoj commented Feb 1, 2022

After trying to understand the (undocumented) codebase, I think I've narrrowed it down some. After debugging usingMathjaxTest and stack-tracing my way through, the documentation never reaches renderPage. I'm can't tell where it gets lost, though. It's so strange that only when applying the annotation does it get lost. Any help?

@IgnatBeresnev
Copy link
Member

Hi! I tried debugging it too, thinking it was an easy fix, but there's definitely something shady going on.

I don't remember much detail, but I believe it embeds the script into the HTML just fine. You can try generating dokka for usesMathjax and looking into the .html sources, you should see

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.6/MathJax.js?config=TeX-AMS_SVG&amp;latest" async="async"></script>

but for some reason the script is not kicking in and not formatting the formulas (now that I think of it, I should've checked if it was under <head> and everything was correct).

If you get to the bottom of this and submit a PR, I'll be happy to merge it :)

@wyskoj
Copy link
Contributor Author

wyskoj commented Feb 2, 2022

Can I ask how you're looking at the output source that usesMathJax is generating? I've just been throwing a print statement on the return of the testInline function but is there a way to actually have it write the pages to files?

I'm noticing that yes, the MathJax CDN is being included, but the paragraph block that contains the text of the documentation is completely missing.

@wyskoj
Copy link
Contributor Author

wyskoj commented Feb 3, 2022

Never mind, I wrote this which outputs it to a directory—which goes inside the renderingStage block.

writerPlugin.writer.contents.entries.forEach {
  File("build/test/nomathjax/${it.key}").also { File(it.parent).mkdirs() }.writeText(it.value)
}

@wyskoj
Copy link
Contributor Author

wyskoj commented Feb 3, 2022

Think I figured out the bug. When applying the @usesMathJax tag, Dokka treats this as something like @param or @author. But since it doesn't recognize it, it throws it out. About to open a PR that should resolve this.

@wyskoj wyskoj mentioned this issue Feb 3, 2022
Merged
@IgnatBeresnev
Copy link
Member

Nice, good job! :) I'll have a look at it today, thanks!

vmishenev pushed a commit that referenced this issue Feb 21, 2022
@wyskoj
Fix MathJax rendering bug (#2342)
f54597c 
* Fix MathJax rendering bug (#2175)

Fix a bug where using the `@usesMathJax` custom tag would cause the
documentation to fail to render.
vmishenev pushed a commit that referenced this issue Apr 1, 2022
@wyskoj @vmishenev
Fix MathJax rendering bug (#2342)
3384d34 
* Fix MathJax rendering bug (#2175)

Fix a bug where using the `@usesMathJax` custom tag would cause the
documentation to fail to render.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bug
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Fix MathJax rendering bug
2 participants
@IgnatBeresnev @wyskoj