Document all of the directives

[dleen]

fixes #867

Need help with:

• exec_doc

I saw this was recently added in #699 but I couldn't figure it out since I thought the cells were already executed...

• nbflags

It seems like this can be used to pass values to internal functions but I don't know of an example that we can use

• default_cls_lvl

It looks like this was supported in nbdev1, but is it implemented in 2?

• hide_input

This one sounded pretty easy but got confused because there is already a bunch of other ways to hide input so not sure what this is for.

@seeM @jph00 @hamelsmu

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[hamelsmu]

@dleen I'm going to add some notes into #867 on where to find directives in the code (they are kind of spread out) and provide some pointers. It's not necessarily that straightforward. You've also asked some good questions which I'll try to address.

I'll work on this morning, I will ping you when I'm done writing the notes.

🙇🏽 Thanks for opening this PR

[hamelsmu]

@dleen I left some detailed comments here to hopefully get you started, let me know if you have any questions

[hamelsmu]

Regarding the questions you've asked about those directives

• I believe #|default_cls_lvl is yet to be implemented in still on our TODO list
• I believe #| nbflags is kind of advanced at this point perhaps don't worry about this one just yet

The rest should be answered in the notes I added to the issue

[jph00]

#|default_cls_lvl is going to be moved into frontmatter and will change a bit anyway. #| nbflags is being removed.

Note that you can think of frontmatter as the same as directives, except directives are for a cell, whereas frontmatter is for the whole NB.

[hamelsmu]

Thanks so much @dleen looking good. I left some comments for you to consider. Please let me know if you have any questions!

BTW this is part of the magic of nbdev code reviews, you can talk about code and documentation in a single context and refine deep understanding of many concepts of a code base!

I ❤️ that you are doing this, this is the best way to learn a code base IMO, and also becomes an amazing contribution 🙇🏽

[hamelsmu]

@dleen updated some comments in case you are relying on email notifications (I would read them on GitHub instead). Thanks again!

[jph00]

Many thanks for the PR @dleen . It looks great, and I've just got some minor requests for you.

It looks like you've accidentally exported a module from your tutorial notebook so we should fix that.

[dleen]

View the latest version: https://dleen.github.io/nbdev/explanations/directives.html

[hamelsmu]

@dleen thanks so much for these changes! I'm going to do some very minor cleanup things on this branch before merging if that is ok.

[dleen]

Yep, no objections! At this point it's probably far quicker to just make the edits than type them out here as comments

[hamelsmu]

@dleen can you add me as a collaborator on your fork please? Nevermind

(I am still working on it will continue tomorrow)

[dleen]

@dleen can you add me as a collaborator on your fork please? Nevermind

(I am still working on it will continue tomorrow)

Done!

[hamelsmu]

Ok, I actually made some significant changes to the layout of this, I tried really hard to maximize the readability of this cheat sheet.

• Changed the introduction section to give more of an overview of directives, and introduce the emojis
• Categorized the directives by functionality
• Placed examples of using directives in collapsible callouts. Without this visual distinction, the document started to become too visually confusing and unnavigable.
• Set the TOC depth to 2, because otherwise the TOC was too confusing
• Placed a header on the cell execution section of the show_doc explainer page so that I could link to it from this directive page.

[Isaac-Flath]

This is awesome! This will definitely be a go-to resource for me :)

One additional directive I use often with quarto is #| include: false which combines echo and output to hide both code and output that may be nice to include in that section.

[Isaac-Flath]

I am just realizing the quarto's #| hide does the same thing as Quarto's #| include so maybe not needed after all if nbdev's implementation is preferred.

[hamelsmu]

Amazing find @Isaac-Flath where did you find that in the Quarto docs? Perhaps we should deprecate #|hide in favor of #|include ....

EDIT: I found it here https://quarto.org/docs/reference/cells/cells-jupyter.html#code-output

Okay I'll open an issue about this