Better docs for reexported packages #2046
Conversation
|
TODO:
|
docs/src/models/functors.md
Outdated
| # Functor from Functors.jl | ||
|
|
||
| Flux makes use of the [Functors.jl](https://github.com/FluxML/Functors.jl) to represent many of the core functionalities it provides. | ||
|
|
There was a problem hiding this comment.
This seems a bit vague to me... first, this use of "functor" belongs to a tiny nice of functional programming, I don't think it's worth putting any emphasis on that here, it's just some package with a weird name. (I mean the title, and the paragraph just below where I can comment.)
Second, I don't know what "many of the core functionalities" means. I wrote something but maybe giving examples (params, training, gpu) would be nice too.
| # Functor from Functors.jl | |
| Flux makes use of the [Functors.jl](https://github.com/FluxML/Functors.jl) to represent many of the core functionalities it provides. | |
| # Recursive transformations from Functors.jl | |
| Flux models are deeply nested structures, and [Functors.jl](https://github.com/FluxML/Functors.jl) provides tools needed to explore such objects, apply functions to the parameters they contain, and re-build them. | |
I can't make suggestions below this, but (IMO) it might also be worth separating the list of functions according to level of obscurity. Maybe @functor, functor, isleaf, fmap should be in one block, the rest in another? Or just @functor, fmap as the top? Not sure, maybe it's too messy to make such a division.
There was a problem hiding this comment.
The number of docstrings looks too few for a further division; should I still divide them?
There was a problem hiding this comment.
I would think of and describe functors like you would the module system of any other library. Because while it is a general-purpose library, that's what we use it for in Flux. One way to do this could be to show practical examples of using @functor etc. to define layers, and then explain what is happening along with why things are done this way. If that last part is too much, just the examples, module system mention and a link to the advanced model building page could suffice.
Co-authored-by: Michael Abbott <[email protected]>
Saransh-cpp
force-pushed
the
reexported-docs
branch
from
c61beca to
2fe8c10
Compare
| @@ -1,4 +1,4 @@ | |||
| # MLUtils.jl | |||
| # Working with data using MLUtils.jl | |||
There was a problem hiding this comment.
I can't comment below, but flatten appears on this page (as it should), and also here:
https://fluxml.ai/Flux.jl/latest/models/layers/#Flux.flatten
Should it be removed?
There was a problem hiding this comment.
Correction: MLUtils.unsqueeze cross-references MLUtils.flatten, and the doctests fail if I remove MLUtils.flatten's reference from the docs.
| "NNlib" => "models/nnlib.md", | ||
| "Functors" => "models/functors.md" | ||
| "Neural Network primitives from NNlib.jl" => "models/nnlib.md", | ||
| "Functor from Functors.jl" => "models/functors.md" |
There was a problem hiding this comment.
One more thought. Should Zygote.jl be among the packages which gets a sidebar heading?
Co-authored-by: Michael Abbott <[email protected]>
|
Let's merge this and refine more if we need to, later. Thanks! |
|
Thanks for the review! I missed the |
* remove linear_regression.jl (commited by mistake) * @ToucheSir's comments * Update Functor.jl's sidebar title
Closes #2038
This PR -
NNlibwith Add minimal infrastructure for the docs NNlib.jl#431Discussion
There is a tutorial (or more precisely, a getting-started/how-to guide) on
DataLoaderavailable here - https://fluxml.ai/tutorials/2021/01/21/data-loader.html. Should this be shifted to the new "Getting Started" section?Originally posted by @Saransh-cpp in #2038 (comment)
PR Checklist