blender/blender-developer-docs
7
8
Fork 38
Code Issues 3 Pull Requests 6 Activity

Improve MathJax Performance and Accessibility in Documentation #82

New Issue
Open
opened 2024-10-14 10:14:55 +02:00 by Vinay-Khanagavi · 3 comments
Vinay-Khanagavi commented 2024-10-14 10:14:55 +02:00
Copy Link

Description:

The current MathJax integration in the Blender documentation, while functional, has opportunities for improvement in terms of performance, accessibility, and maintainability.

Here's a breakdown of the key areas:

  • Performance: Typesetting the entire document on every update can cause lag, especially on pages with numerous mathematical expressions or for users on lower-powered devices.
  • Accessibility: While MathJax offers accessibility features, the current setup might not be leveraging them fully, potentially limiting access for users with disabilities.
  • Maintainability: Embedding the MathJax configuration directly within a JavaScript file makes it less maintainable and harder to update.

These issues could lead to a less-than-ideal user experience for those who rely on the Blender documentation.

Solution:

This PR addresses these areas with the following changes:

Performance:

  • Targeted Typesetting: Only re-render changed math elements:
// ... Inside document$.subscribe callback:
const mathElements = document.querySelectorAll('.arithmatex'); 
MathJax.typesetPromise(mathElements);
  • Debouncing: Limit typesetting frequency:
// ... Debounce function (using Lodash or similar):
document$.subscribe(debounce(() => { 
    // ... (typesetting logic) 
}, 250));

Accessibility:

  1. Enable MathML output: Configure MathJax to output MathML (see MathJax docs).
  2. Test keyboard navigation: Ensure keyboard accessibility for math elements.

Configuration:

Create mathjax-config.js: Move configuration options to a dedicated file:

window.MathJax = {
    // ... your configuration options
};

Error Handling:

Use MathJax's error API: Provide user-friendly error messages:

MathJax = {
    // ...
    errorHandler: (errors) => {
        console.error("MathJax errors:", errors); 
        // ... additional error handling
    }
};
image
### **Description:** The current MathJax integration in the Blender documentation, while functional, has opportunities for improvement in terms of performance, accessibility, and maintainability. Here's a breakdown of the key areas: - Performance: Typesetting the entire document on every update can cause lag, especially on pages with numerous mathematical expressions or for users on lower-powered devices. - Accessibility: While MathJax offers accessibility features, the current setup might not be leveraging them fully, potentially limiting access for users with disabilities. - Maintainability: Embedding the MathJax configuration directly within a JavaScript file makes it less maintainable and harder to update. These issues could lead to a less-than-ideal user experience for those who rely on the Blender documentation. ### **Solution:** This PR addresses these areas with the following changes: **Performance:** - Targeted Typesetting: Only re-render changed math elements: ``` // ... Inside document$.subscribe callback: const mathElements = document.querySelectorAll('.arithmatex'); MathJax.typesetPromise(mathElements); ``` - Debouncing: Limit typesetting frequency: ``` // ... Debounce function (using Lodash or similar): document$.subscribe(debounce(() => { // ... (typesetting logic) }, 250)); ``` **Accessibility:** 1. Enable MathML output: Configure MathJax to output MathML (see MathJax docs). 2. Test keyboard navigation: Ensure keyboard accessibility for math elements. **Configuration:** Create mathjax-config.js: Move configuration options to a dedicated file: ``` window.MathJax = { // ... your configuration options }; ``` **Error Handling:** Use MathJax's error API: Provide user-friendly error messages: ``` MathJax = { // ... errorHandler: (errors) => { console.error("MathJax errors:", errors); // ... additional error handling } }; ``` <img width="344" alt="image" src="attachments/013e4fdc-3e85-4576-a5ca-cc2009cdc616">
Julian Eisel commented 2024-10-14 11:55:55 +02:00
Member
Copy Link

Thanks for the contribution. Our MathJax integration follows the Material for MkDocs documentation with minimal changes to reduce maintenance burden. If there are improvements to be made, they should be submitted to them to evaluate, we can then follow their decisions.

As for the proposed changes:

  • Performance: We only use MathJax for occasional, simple maths expressions, so performance shouldn't be a concern generally. Pages are delivered as static HTML with barely any custom interaction handling, so I think re-rendering or debouncing improvements should not have much of an impact. Performance improvements should always be measured, many apparent improvements turn out to be regressions.
  • Accessibility: Best propose this to Material for MkDocs directly, might be worthwhile improvements.
  • Configuration: The configuration is already in a dedicated file.
  • Error Handling: The only information this adds is that the errors are from MathJax? I think this is already visible, but sure, might make debugging a bit easier. Might be worth proposing to Material for MkDocs too.

Lastly this appears to be a AI generated list of improvements. I'd consider it good practice to indicate this, so reviewers are aware that the suggestions may not actually be applicable to their specific case (AI generated improvements are very general and lack context).

Thanks for the contribution. Our MathJax integration follows the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/math/) documentation with minimal changes to reduce maintenance burden. If there are improvements to be made, they should be submitted to them to evaluate, we can then follow their decisions. _As for the proposed changes:_ - Performance: We only use MathJax for occasional, simple maths expressions, so performance shouldn't be a concern generally. Pages are delivered as static HTML with barely any custom interaction handling, so I think re-rendering or debouncing improvements should not have much of an impact. Performance improvements should always be measured, many apparent improvements turn out to be regressions. - Accessibility: Best propose this to Material for MkDocs directly, might be worthwhile improvements. - Configuration: The configuration is already in a dedicated file. - Error Handling: The only information this adds is that the errors are from MathJax? I think this is already visible, but sure, might make debugging a bit easier. Might be worth proposing to Material for MkDocs too. Lastly this appears to be a AI generated list of improvements. I'd consider it good practice to indicate this, so reviewers are aware that the suggestions may not actually be applicable to their specific case (AI generated improvements are very general and lack context).
Vinay-Khanagavi commented 2024-10-14 12:16:58 +02:00
Author
Copy Link

I apologize if my initial suggestions were too general and didn't fully consider the Blender's documentation and its reliance on Material for MkDocs. You are right that for occasional, simple math expressions and a statically generated site!

In the future, I will clearly indicate if and how AI tools were used in my suggestions to ensure transparency.

And I'll suggest the error handling improvement, as having clearer error messages can be helpful for maintainers and potentially users.

  • Material for MkDocs can leverage MathJax's built-in error handling to capture and process errors. One approach I thought was to use the errorHandler property within the MathJax configuration
I apologize if my initial suggestions were too general and didn't fully consider the Blender's documentation and its reliance on Material for MkDocs. You are right that for occasional, simple math expressions and a statically generated site! **In the future, I will clearly indicate if and how AI tools were used in my suggestions to ensure transparency.** And I'll suggest the error handling improvement, as having clearer error messages can be helpful for maintainers and potentially users. - Material for MkDocs can leverage MathJax's built-in error handling to capture and process errors. **One approach I thought was to use the errorHandler property within the MathJax configuration**
Vinay-Khanagavi commented 2024-10-14 12:27:09 +02:00
Author
Copy Link

Added errorHandler

this new window.MathJax will help maintainers in for easier debugging.

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  },
  startup: {
    ready() {
      MathJax.startup.defaultReady();
      MathJax.Config({
        showErrorMessages: true, 
      });
    },
  },
  errorHandler: (errors) => {
    console.error("MathJax encountered errors:", errors); 

  }
};

document$.subscribe(() => { 
  MathJax.startup.output.clearCache()
  MathJax.typesetClear()
  MathJax.texReset()
  MathJax.typesetPromise()
})

If the proposed changes is not important then it's okay, I appreciate you're point on the importance of maintaining consistency with Material for MkDocs, yes as it minimizes maintenance overhead.

Thanks again for your time and consideration of my suggestions!

Added errorHandler this new window.MathJax will help maintainers in for easier debugging. ``` window.MathJax = { tex: { inlineMath: [["\\(", "\\)"]], displayMath: [["\\[", "\\]"]], processEscapes: true, processEnvironments: true }, options: { ignoreHtmlClass: ".*|", processHtmlClass: "arithmatex" }, startup: { ready() { MathJax.startup.defaultReady(); MathJax.Config({ showErrorMessages: true, }); }, }, errorHandler: (errors) => { console.error("MathJax encountered errors:", errors); } }; document$.subscribe(() => { MathJax.startup.output.clearCache() MathJax.typesetClear() MathJax.texReset() MathJax.typesetPromise() }) ``` If the proposed changes is not important then it's okay, I appreciate you're point on the importance of maintaining consistency with Material for MkDocs, yes as it minimizes maintenance overhead. Thanks again for your time and consideration of my suggestions!
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
No items
No Label
Milestone
Clear milestone
No items
No Milestone
Assignees
Clear assignees
No Assignees
2 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: blender/blender-developer-docs#82
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?