Documentation issues

1

I will likely come back here and dump stuff that I find for fixing.

The documentation is overall slightly messy, somewhat incomplete. Hence it would be nice if inconsistencies could be minimised as much as possible.

Question: Have you thought about improving the system how the documentation is generated? I asked that before but never really got answers. Maybe it could be improved from the ground up, maybe keeping things in mind like update-ability that is closer to the source and maybe also compatibility with documentation styles that are more common and hence could be implemented in apps like Dash.

1

GSFont.instances > Sample code says

# to delete an axis
del(font.instances[0])

:red_circle:# to delete an axis
:green_circle:# to delete an instance

2

a)

There is inconsistency between del <something> and del(<something>). This is a bit confusing, especially for less experienced users. Please consider choosing one and updating the documentation.

b)

Whenever there are several ways to delete something, for example:

del(font.instances[0])
# or
font.instances.remove(someInstance)

Consider presenting only one optimal way. This also causes confusion.

  • .remove() seems to be added to the wrapper, while del appears to be legacy. (?)
  • if remove() cannot handle deleting instances by index from the font (as del shows), consider adding that to the wrapper.

Please consider adding an “equivalent to” to the comments.

3

a)

GSInstance.customParameters > Sample code has some quotes too many (or too few)

# 👇 here you see it easily, where the syntax highlighting goes loco.

parameter = GSCustomParameter("Name Table Entry", "1 1;"font name")
font.customParameters.append(parameter)
parameter = GSCustomParameter("Name Table Entry", "2 1;"style name")
font.customParameters.append(parameter)

b)

The sample code shows how to add the CP to the Font but it is under GSInstance. To avoid confusion, consider sorting that out. Either change it here, or move it to GSFont . Or show both in both places and add a comment that it can be added to font or instance.

4

Consider unifying quote style. Either double or single. The sample code from point 3 has even both in one block.

Checklist

  • 1
  • 2a
  • 2b
  • 3a
  • 3b
  • 4
2

Hmm. These are two pythonesque ways of removing items from a list, by index or by object. See python.org: 5. Data Structures — Python 3.12.1 documentation

1 Like
3

Fair enough. Then please consider adding an “equivalent to” to the comments. (added this above).

4

If you have a better idea I’m listening. Right now the documentation is generated from the source code of the python wrapper. It doesn’t get much closer.

That are two different things.
The first line removes based on the index/key, the second remove an actual item. Why del and len is still a keyword and print isn’t is beyond me. But that it is in python. del is not legacy.

5

They are not equivalent.

6

The wrapper file is in the GlyphsSDK. I just updated it with from the 3.2 branch (after I incorporated your suggestion).

You can check the code and fix it yourself if you like :wink:

7

Thanks a lot. I’ll have a look and report back :green_heart: