Update for 2025

[qwertychouskie]

The working state of my gm0 update project. As categories/pages get completed, they get split out into separate PRs.

So far:
#464 (merged)
#467 (merged)
#468 (merged)
#470 (merged)
#472 (merged)
#473 (merged)
#475

[PythonAtSea]

IMO, we should point new teams towards onshape pretty strongly. I know some people prefer fusion because it can do renders, or because they like the design style better, but for a new team that hasn't ever touched CAD those don't really matter, and Onshape's part lib is a very strong selling point

[abidingabi]

I agree with this; CAD software is one of a couple examples of areas where there is a pretty clear specific option to recommend. We should still discuss other CAD software, but Onshape should be what we recommend.

[qwertychouskie]

I have a quick question, what was the reasoning behind #417? Not wanting things like smart quotes ans such makes sense, but blacklisting every UTF8 character seems too heavy-handed, e.g. having to use \ |reg| instead of ® makes certain areas a pain (e.g. look at the license page update commit in my PR). Even just whitelisting ©®™℠ would make things a lot easier. Would it be OK if I pushed an update to the check script to whitelist certain characters?

[abidingabi]

I have a quick question, what was the reasoning behind #417?

First, as you correctly surmised, people would quite frequently accidentally include e.g. curly quotes when copying from e.g. Google Docs. I also personally had a habit of using literal em-dashes which probably is not great from an editing perspective.

Secondly, at least some unicode characters (i.e., →) did not render correctly in the PDF output. This can probably be fixed by switching LaTeX engines. I would be perfectly fine with whitelisting those unicode characters as long as they work in our current PDF build pipeline.

Alternately, if we can get the PDF build to work for unicode in general, we should probably instead denylist specific unicode characters (i.e. ‘ ’ “ ” – — or so). This is probably preferable but also probably more annoying—I remember looking into this at some point and giving up.

I would also like to note that the exclusion of the license from the actual text of the manual was intentional so that it would be omitted from the PDF build, as it is quite long and would be kind of a waste of space in that context. As such, it may be wise to gate its inclusion on the output format being HTML which can be done with

.. only:: html
   license text goes here

or so, but I do not have strong opinions on this.

[qwertychouskie]

I have a quick question, what was the reasoning behind #417?

First, as you correctly surmised, people would quite frequently accidentally include e.g. curly quotes when copying from e.g. Google Docs. I also personally had a habit of using literal em-dashes which probably is not great from an editing perspective.

Secondly, at least some unicode characters (i.e., →) did not render correctly in the PDF output. This can probably be fixed by switching LaTeX engines. I would be perfectly fine with whitelisting those unicode characters as long as they work in our current PDF build pipeline.

Alternately, if we can get the PDF build to work for unicode in general, we should probably instead denylist specific unicode characters (i.e. ‘ ’ “ ” – — or so). This is probably preferable but also probably more annoying—I remember looking into this at some point and giving up.

I would also like to note that the exclusion of the license from the actual text of the manual was intentional so that it would be omitted from the PDF build, as it is quite long and would be kind of a waste of space in that context. As such, it may be wise to gate its inclusion on the output format being HTML which can be done with

.. only:: html
   license text goes here

or so, but I do not have strong opinions on this.

Alright, I'll probably start with just whitelisting some characters for now as that seems like the least invasive change and the easiest to validate that nothing broke.

BTW, @abidingabi do you have the original vector version of the gm0 logo? I want to update the favicon to look proper on dark mode web browsers (currently it's mostly illegible due to black-on-dark-gray), and for that I need a vector image (specifically SVG, but any vector format is fine as I can then export to SVG). Alternatively, if you at least know what font was used, that would allow me to re-create the logo.

[abidingabi]

BTW, @abidingabi do you have the original vector version of the gm0 logo?

Yep, here it is as a github gist because embedding it seems to have broken it somewhat.

[qwertychouskie]

BTW, @abidingabi do you have the original vector version of the gm0 logo?

Yep, here it is as a github gist because embedding it seems to have broken it somewhat.

Awesome, thanks! The favicon looks much better already (old left, new right):

[qwertychouskie]

Is this better or worse than what I posted in the previous post? The "zero" is definitely more legible, but also it arguably might not look as good. Thoughts?

[abidingabi]

Personally, I think that is worse; I think the logo is pretty recognizable from its shape perspective even if the zero is not super readable, and changing that seems unwise.

[qwertychouskie]

SVG logo and favicon stuff should all be solid now.

I'm thinking about splitting the non-content commits (so the first 5 commits) into a separate PR ready to be reviewed and merged right away. I think I've done all such changes, the logos/favicon was kinda the last big one. Oh, I guess the change to whitelist certain UTF characters is not in those 5, but that should perhaps be a separate PR, since a bunch of content will be updated as well.

[qwertychouskie]

sphinx-hoverxref is deprecated in favor of https://docs.readthedocs.com/platform/stable/link-previews.html, can someone with the necessary admin privileges enable it so I can remove the deprecated package?

For reference, this is the current sphinx-hoverxref config:

# Enable hover content on glossary terms
hoverxref_roles = ["term"]
hoverxref_role_types = {
    "term": "tooltip",
}

# Required to display LaTeX in hover content
hoverxref_mathjax = True
# Use MathJax3 for better page loading times
mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'

[qwertychouskie]

I keep flip-flopping on favicon stuff. The main issue is the 16x16 favicon on low-DPI displays

Which is preferable, "orange pixel blob" or "not accurate to the logo but it's legible"?

[abidingabi]

I have enabled link previews on all the copies of gm0 on read the docs.

I think using the original logo is preferable; the graphical consistency is really important The favicon is rendered small enough that either way that it’s purpose is to be visually recognizable, not read, and so the legibility of the text is not critical here.