Hey folks, I'm looking at adding test (and maybe listing or formatting?) To the code samples in the docs, after I found that some had drifted out of date. While I roll this idea around my head conceptually, can you help me understand the boundaries of this space: • If I were to codegen files out of the docs, could we run linters against those generated sources? • Can we put nonprinting stuff in the markdown? For example, if we had code that was

foo(a,b)

, could we "hide" the setup required (eg

import foo

) in the doc? I think the 2 biggest problems would be: • Some examples have BUILD files. We could get around this as a problem by using a rule_runner the way we do with plugin integration tests. • Running fixers against these code samples. Not sure how that could work

For what it's worth, we use Readme.com currently. Since our aim to is to migrate soon away from Readme to something like Sphinx or Jupyter Book, I would recommend not relying too heavily on readme proprietary features. But their docs may be able to answer questions such as the one about nonprinting chars in markdown. (I don't know that answer offhand, unfortunately.)

Definitely a feature to take into account when we migrate

Probably worth capturing in a GitHub discussion?

Paging @loud-laptop-89838 as well for that conversation, since he's currently working on a jupyter-book backend for Pants. (Woot!)

And jupyter book is just a wrapper for sphinx that basically allows you to use jupyter notebooks alongside myst docs. So if those are the two options you're looking at then using myst syntax for now gives you the most flexibility

So I think bullet 1 is conceptually easy, 2 is 🤷‍♂️

You can do #2 in jupyter-book. You just mark the code cell with a tag. You can have tags to show only code, only results, neither, or both.

They sounds awesome

Hope so!

Someone please kick off that GH Discussions conversation 🙂

You mean a discussion on documentation? Seems like it's coming up a lot. You're likely right to get the conversation documented