Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Convert tutorial markdown to jupyter notebooks and publish using nbsphinx #2027

Open
cmungall opened this issue Mar 26, 2024 · 0 comments
Open
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@cmungall
Copy link
Member

Currently the tutorial is hard to maintain - it uses a homegrown format to run all embedded scripts and check results against what is there.

Instead we could just author the tutorial as notebooks, in the docs/ folder, enable nbsphinx which will render them (statically) as part of the docs. It's then very easy to extend the tutorial or add new examples or change examples in existing pages.

We currently do this in the linkml-transformer repo, here is an example
https://linkml.io/linkml-transformer/#examples/Tutorial/
But note this is a mkdocs repo, we use mknotebooks which may look different

Some potential downsides

  1. Our tutorials focus on command line usage rather than python usage. The !s to run a script in bash may be distracting
  2. The documentation may end up looking like a notebook, e.g. with numbered cells (todo: investigate if nbsphinx allows disabling this; I like how it looks in mknotebooks
@nlharris nlharris added documentation Improvements or additions to documentation enhancement New feature or request labels Mar 28, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants