Are you not getting the css style then? My docs.fasta.ai looks different
Ah, thank you for that validation, @ashaw - it looks like a problem in the old firefox I use - I re-checked in chrome and it does appear as your snapshot.
So it’s a non-issue. Thanks again.
1 Like
Can someone improve this doc entry: https://docs.fast.ai/data_block.html#ItemList.get_label_cls
so that the code matches the doc? It doesn’t show how get_label_cls is used.
Thanks.
I will go through the data block API in the near future and systematically add new examples and fix legacy examples.
Give me a few days.
2 Likes
A useful thing came out from this discussion with @Kaspar.
We currently hide all import statements in the API nbs. But we should only hide what’s not to be seen, but more precisely we shouldn’t hide the important imports.
So you can see in the modified version of https://docs.fast.ai/utils.ipython.html#utils.ipython
while it still hides the show_doc-related imports it shows the important import:
from fastai.utils.ipython import *
Unless there are objections, I think all API nbs should do that.
Any takers to do it for all nbs?
@ashaw, can we please also modify the doc skeleton generator to create two code cells for imports, one hidden as it is now and another not hidden with just the one line import for that module? as I have done it with https://docs.fast.ai/utils.ipython.html#utils.ipython
update: Discussed this more with the devs, and the agreement is that unless the doc has examples at the top, e.g. https://docs.fast.ai/vision.html, then we want to have the page start with:
“To import the foo module, use:” from foo import *
So here is the model to replicate: https://docs.fast.ai/utils.ipython.html#utils.ipython
@ashaw, another little thing about anchors.
If you go to: https://docs.fast.ai/utils.ipython.html#utils.ipython it takes you to TOC/h1, and not the utils.ipython entry. so we have a dupe here in tags, since both have the same name.
How can I link to that first h2 utils.ipython entry? e.g. I encountered that in the post above where I was trying to show the import line, but it is taking the reader elsewhere.
1 Like
Wow nothing slips past you 
How’s this - https://github.com/fastai/fastai/pull/1769
I renamed the title so they no longer collide. It also makes the format more consistent with the other document pages
The other option - checking for duplicate IDs - is kind of a pain
1 Like
Your suggestion works, @ashaw.
So we need to manually rename the first <h2> to resolve this.
And when a skeleton is generated it should say “rename me to a brief title, which is not module name”, right?
Yup. Just updated with clearer instructions
1 Like
What about -
“To use the utils.ipython module:”
from fastai.utils.ipython import *
Including “import” and “fastai.” in the title seems a little redundant
1 Like
I find utils.ipython is already confusing in the title, since you can’t import it and need to remember to add fastai.
Perhaps just:
“To use this module:”
from fastai.utils.ipython import *
2 Likes
Much better
1 Like
I started adding imports to a few of the docs, but then decided against it.
It feels a little redundant to add from fastai.vision import * on all the vision submodules. Same with callbacks.
In my opinion, the utils confusion is very specific edge case. All the other fastai submodules are imported automatically from the top level.
Most of our overview pages contain import examples. I’ve added some for the ones that don’t
If someone still feels strongly about it, feel free to take up this task!
Here’s the code (if needed) for the docs api side:
Ah, this makes sense often, but users don’t always import fastai.basics or modules that include it that import it all.
Here is a simple example. When you write a callback module you need to:
from fastai.callback import Callback
Yet, it’s not mentioned anywhere on https://docs.fast.ai/callback.html
The callbacks example makes a lot of sense. We should definitely add that to the intro.
But for things like callbacks.fp16 it gets confusing.
What should the user import?
It’s imported automatically for application specific modules - vision, text, etc.
Telling them to import either fastai.basics, fastai.callbacks, fastai.callbacks.fp16, etc would be redundant in those cases
Excellent. So the conclusion is that some docs need this improvement, whereas others it’d be just confusing. So we don’t need to do a global fixup, but to fix things as we refer to those pages and find that import call is missing and needed.
And then the final question - should the skeleton show import * and then let the editor to decide to hide it or have it hidden by default?
1 Like
I think hidden by default. I can add a comment in the cell telling the user it’s hidden and suggest unhiding it if applicable
we do not import fastai.basics because jeremy that it was not necessary
That’s why I wrote: “users don’t always import fastai.basics or modules that include it” 