Request for feedback: Documentation helper

Community Help
1

tl;dr: Wrote an API doc helper for Observable, check it out, let me know whatcha think.

I’ve started to write my own library notebook and included a helper that is supposed to make documenting and testing functions a breeze. Implementation goals:

  1. Require minimal configuration (i.e. sane defaults)
  2. Be flexible, handle a broad range of use cases (i.e. allow to override stuff)
  3. Don’t impose a documentation style (e.g. don’t force jsdoc)
  4. Provide a minimal testing framework

While the library is still very much a work in progress, the helper itself is in a state that I feel comfortable sharing. I’d appreciate it if you took the time to play around with it and share your impressions. Please also let me know if you believe that the API or documentation is missing anything critical.

Thank you!

2 Likes
2

I played around with it a little. https://observablehq.com/@bchoatejr/matrix-utilities I like it. I like being able to combine SVG, tex, tests, into the code documentation. Here are some things I wrote down.

  • Do you have any examples of using a different style? I was going to try to change the documentation background cell to be different for the docs versus the actual code. I saw the scope, css parameters in the options, a simple example would be useful.
  • link and name don’t work if the function is one line arrow, or arrow function. Example in the notebook. Setting name directly in the option makes link work.
  • if a linked cell is used for the description option it disappears when referenced. but reappears when run again after removing from description option. Doesn’t really matter to me, seems better, less clutter.
  • examples I would be interested in: chart output on tests, different style options.

Thanks for putting this together.

1 Like
3

Glad to hear that, then I’ve reached my goal. :slight_smile:

There are many ways to skin that cat, but all involve importing signature_theme. I’m currently looking into ways to make minor CSS changes easier. Let me get back to you on this.

That’s because arrow functions have no name. The docs are now updated to make this point clearer and explain how name can be used as a fallback. I’m still considering to split name up into name and href, i.e. use name only to override the function name, and provide an explicit link via href.

I’ve also rewritten the signature parsing. If you update the linked revision in your notebook you should only see the function heads, even for arrow functions.

The reason is that mm_def5 is a DOM node that’s already attached to the DOM. Assigning it to description effectively reattaches the cell node under a new parent, because everything that’s not a string gets passed through. In that case I’d recommend recreating the element from its HTML:

{description: html`${mm_def5.outerHTML}`}

Can you give an example regarding the chart output? The defaultTestRunner only passes in assert() and handles throwing, but with a custom testRunner and/or custom test formatters you can do a lot more.

Thank you for taking the time to test and give feedback!

1 Like