Explainer for gh-scoped-creds to docs

[jbusecke]

I somehow thought that we already had an explainer about how to authenticate to gh with gh-scoped-creds.
We currently link to the 2i2c docs, but people seem to miss this often.

This would be a great use case to 'embed' a section of the 2i2c docs tracking any upstream changes in the process.

@jmunroe we talked about this a while ago and I was wondering if there is a recommended way to achieve this?

[jbusecke]

Just a note that it would be nice to have the gif animation from yuvis blog post either in our docs, or ideally in the upstream docs https://blog.jupyter.org/securely-pushing-to-github-from-a-jupyterhub-3ee42dfdc54f

[jmunroe]

Hi @jbusecke . 2i2c some recently onboarded a new team member, @jnywong , to work on improving all aspects of our technical documentation. I see one of the outputs from this is a renewed focus on JupyterBooks for creating and curating documentation.

If there was a single markdown file (written with the intention of being included in a JupyterBook) that that covered gh-scoped-creds, perhaps LEAP could reuse that markdown file.

The low-tech solution would be straight copy of the upstream markdown file. I wonder if the JupyterBook folks have ever thought about a way of linking against a mark down file that lives at the some URL.

Anyways, I'll have the discussion with @jnywong and follow back with you if the that something we can turn around in the next week or so.

[jbusecke]

That would be great! Thanks for keeping me in the loop.

[SammyAgrawal]

@SammyAgrawal

[jnywong]

Hey! I think the embedding of content is where a recently introduced MyST functionality would come in super useful here https://mystmd.org/guide/embed#embed-from-external-myst-projects.

This is currently not available for our 2i2c docs that are based on Jupyter Book technology, but if we find traction (both us at 2i2c and you at LEAP) around using a MyST ecosystem, then this MyST "embed" tool allows the sharing of materials in this way more effective.

Sorry that this doesn't solve your ask for now. I've just updated the docs on gh-scoped-creds in the 2i2c Service Guide and you can use the "low tech solution" to extract excerpts from the source markdown file as required.

[SammyAgrawal]

Oh cool, that seems super useful potentially for the future! Thanks will check out

[jbusecke]

Awesome, thanks @jnywong! It also seems that Jupyer Book is moving to use myst in version 2 so maybe this will come for free?

[jnywong]

Yep, "anything" in a JB2/MyST deployment is embeddable. it's linkable right now in JB1, but there's no rich preview 👍