Move doc sections to "guide" + "reference" #2115

mcabbott · 2022-11-19T20:28:37Z

This is one take on how we might aim to organise the docs. No new text, just moving headings around.

The goal is to separate it into

A guide you could read straight through, and encounter each idea once. Basics first, more specialised later.
A reference section, to look up all the weird loss functions / layers / etc, mostly just docstrings
A tutorials section, into which we move what's now on the website, and maybe the model zoo. Each should solve some problem, ideally data -> model -> results. Fine if they overlap.

This seems like a non-awful way to present things, which can be achieved without re-writing more than we have to. The sections which most awkwardly straddle guide/reference are the training/optimisation/regularisation ones, which need re-working for explicit params anyway. #2114 is a start.

One downside of this is that some things like onehot and outputsize don't really appear in the "guide" half at all. Maybe they ought to be squeezed in somewhere?

Edit, more comments:

~~Maybe "Fitting a Line" and "Quickstart" also straddle the guide/tutorial boundary a bit. Could think about moving them there.~~ Maybe I like the choice of fast/slow intro. I see now that this was what the original overview PR envisaged: #1579 (comment) (naming exactly xor as what the quickstart should target!)

Maybe the guide pages should be consolidated a bit -- "performance tips" doesn't say much, can it be rolled into "GPU & performance tips"? "Regularisation" also doesn't say much ... #2114 wants to make it just a section.

Not sure what order these sections ought to be in. One complaint in #2105 is "Ecosystem... is currently way down at the bottom". This could move up, although we can't put everything first... what exactly deserves to go last?

Do tutorials come after reference? Perhaps #2125 was merged in haste, as these tutorials aren't actually much good... maybe one or two should be updated & the rest trashed. The versions on the model zoo have stayed more up to date, maybe people should just read those -- the added text on these versions is often more confusing than helpful.

github-actions · 2022-11-19T20:29:02Z

Once the build has completed, you can preview any updated documentation at this URL: https://fluxml.ai/Flux.jl/previews/PR2115/ in ~20 minutes

ToucheSir · 2022-11-29T00:20:52Z

Is there really no way to selectively collapse larger sidebar sections in Documenter by default? I feel like that would make the high-level order much less important and save us some decision fatigue.

mcabbott · 2022-11-29T00:29:04Z

I looked at a few packages linked from Documenter's docs, and don't see any such thing. But I don't think it's too bad really, you don't have to scroll so far that learning how to use some folding thing would pay.

I wonder today if we should make Ecosystem a top-level heading, with a page for packages containing Flux models, separate from a page of less closely associated links.

I also wonder if we want a page of CUDA docstrings, separate from the current GPU page. For now, https://fluxml.ai/Flux.jl/previews/PR2115/CUDA/

We should probably hide several of these tutorials, at least until they can be updated, but ideally improved. That will also cut the scrolling. And argues for them being last.

mcabbott · 2022-11-29T15:30:17Z

docs/make.jl

-        "Building Models" => [
-            "Built-in Layers 📚" => "models/layers.md",
+            "Training" => "training/training.md",
+            # "Regularisation" => "models/regularisation.md",  # consolidated in #2114


PR started out just re-organising sections.

This commented line should probably stay until #2114

mcabbott · 2022-11-29T15:31:28Z

docs/src/ecosystem.md

+
+---
+
+## Alternatives to Flux


Small changes to the links page. The biggest is this section on SimpleChains / KNet / Lux. See what you think?

mcabbott · 2022-11-29T15:32:33Z

docs/src/index.md


 ## Installation

-Download [Julia 1.6](https://julialang.org/downloads/) or later, preferably the current stable release. You can add Flux using Julia's package manager, by typing `] add Flux` in the Julia prompt.
-
-This will automatically install several other packages, including [CUDA.jl](https://github.com/JuliaGPU/CUDA.jl) which supports Nvidia GPUs. To directly access some of its functionality, you may want to add `] add CUDA` too. The page on [GPU support](gpu.md) has more details.


I tried to delete lots of text from the welcome page. It was pretty verbose.

mcabbott · 2022-11-29T15:33:22Z

docs/src/models/basics.md

@@ -232,6 +232,5 @@ Affine(3 => 1, bias=false, init=ones) |> gpu
 ```

 ```@docs
-Functors.@functor


This macro has its (long) docstring in the Functors page, so it need not appear here (and in fact Documenter complains about it appearing twice)

docs/src/reference/CUDA.md

… saves space on the navigation panel so you can see more other things

ToucheSir · 2022-12-01T04:18:27Z

docs/src/ecosystem.md

+
+* [SimpleChains.jl](https://github.com/PumasAI/SimpleChains.jl) is focused on making small, simple, CPU-based, neural networks fast. Uses [LoopVectorization.jl](https://github.com/JuliaSIMD/LoopVectorization.jl). (Was `FastChain` in DiffEqFlux.jl) 
+
+* [Knet.jl](https://github.com/denizyuret/Knet.jl) is a neural network library built around [AutoGrad.jl](https://github.com/denizyuret/AutoGrad.jl), with beautiful documentation.


Suggested change

* [Knet.jl](https://github.com/denizyuret/Knet.jl) is a neural network library built around [AutoGrad.jl](https://github.com/denizyuret/AutoGrad.jl), with beautiful documentation.

* [Knet.jl](https://github.com/denizyuret/Knet.jl) is a neural network library built around [AutoGrad.jl](https://github.com/denizyuret/AutoGrad.jl).

Is "with beautiful documentation" from a tagline somewhere? Trying to think of a better point of comparison for this bullet.

It is really nice, https://denizyuret.github.io/Knet.jl/latest/mlp/

But I agree this may read as a dismissal. The entire section is a bit of a minefield...

Trying to find a way to express that KNet takes an equally valid but different approach to the ML library design problem. The README and https://denizyuret.github.io/Knet.jl/latest/tutorial/#Philosophy don't give us much in the way of talking points to succinctly contrast against Flux, however.

Yes, this seems aimed more at tensorflow et al, parallel to pytorch / Flux / etc.

docs/src/index.md

ToucheSir · 2022-12-01T04:21:41Z

docs/make.jl

+            "NNlib.jl (`softmax`, `conv`, ...)" => "models/nnlib.md",
+            "Zygote.jl (`gradient`, ...)" => "training/zygote.md",
+            "MLUtils.jl (`DataLoader`, ...)" => "data/mlutils.md",
+            "Functors.jl (`fmap`, ...)" => "models/functors.md",
+            "OneHotArrays.jl (`onehot`, ...)" => "data/onehot.md",


Having example functions right in the heading feels a little strange. Could we instead use adapt the tagline of each page? e.g. "Neural Network primitives - NNlib.jl".

I don't love them, but they are compact, and I didn't manage to think of a better way (last time around). I mean I know what "primitives" means but it's not so obvious... what kind of utils is MLUtils, what on earth is Functors in less than a paragraph?

(They aren't new, and the page titles are longer explanations, which don't fit nicely in the sidebar)

My thought was to take inspiration from the shortened titles, something like so:

Suggested change

"NNlib.jl (`softmax`, `conv`, ...)" => "models/nnlib.md",

"Zygote.jl (`gradient`, ...)" => "training/zygote.md",

"MLUtils.jl (`DataLoader`, ...)" => "data/mlutils.md",

"Functors.jl (`fmap`, ...)" => "models/functors.md",

"OneHotArrays.jl (`onehot`, ...)" => "data/onehot.md",

"Low-level Operations - NNlib.jl" => "models/nnlib.md",

"Taking Gradients - Zygote.jl" => "training/zygote.md",

"Working with Data - MLUtils.jl" => "data/mlutils.md",

"Manipulating Models - Functors.jl" => "models/functors.md",

"One-Hot Encoding - OneHotArrays.jl" => "data/onehot.md",

Last commit does this, see what you think (PR before + after):

Looks pretty good!

Shall we do this, then refine as necc?

Co-authored-by: Brian Chen <ToucheSir@users.noreply.github.com>

docs/src/index.md

mcabbott added the documentation label Nov 19, 2022

This comment was marked as off-topic.

Sign in to view

mcabbott force-pushed the doc_sections3 branch from 214d8c0 to 52f9a54 Compare November 23, 2022 03:56

Saransh-cpp mentioned this pull request Nov 25, 2022

Move 5 tutorials from fluxml.github.io #2125

Merged

mcabbott force-pushed the doc_sections3 branch from 52f9a54 to a5bc162 Compare November 25, 2022 15:33

mcabbott mentioned this pull request Nov 27, 2022

Re-write training docs #2114

Merged

mcabbott force-pushed the doc_sections3 branch from c2a8bf0 to 917b9ad Compare November 28, 2022 20:32

mcabbott force-pushed the doc_sections3 branch 2 times, most recently from 3c850e7 to 8ee5428 Compare November 29, 2022 15:07

mcabbott marked this pull request as ready for review November 29, 2022 15:08

mcabbott commented Nov 29, 2022

View reviewed changes

mcabbott force-pushed the doc_sections3 branch from b4418ee to 4716bd5 Compare November 30, 2022 13:26

mcabbott added 15 commits November 30, 2022 22:54

make guide + reference

25d25a4

try moving Fitting a Line to tutorials

4e56b71

restore Fitting a Line's place

6bd7df7

remove duplicate functor docstring (it's in Functors section)

082fe4b

alter "Learning Flux" section to match

7b4cfb6

reduce the amount of text on welcome page

e8ca198

add a CUDA.jl reference page

02a3635

add Alternatives to Flux section

e0b62c0

fixup

17c49cb

hide some tutorials, try moving Ecosystem up

4f6015c

remove the 📚 marker

9d5b5cc

tweaks to links page

d7d07ec

trim even more surplus text from welcome page

b222b04

rm CUDA page

81fb2a3

the welcome page is short enough not to need navigation, and using H3…

cbdc154

… saves space on the navigation panel so you can see more other things

mcabbott added 2 commits November 30, 2022 22:54

fix misleading sentence in nnlib intro

7b48d24

remove CUDA

a0d90b8

mcabbott force-pushed the doc_sections3 branch from 4716bd5 to a0d90b8 Compare December 1, 2022 03:56

ToucheSir reviewed Dec 1, 2022

View reviewed changes

Apply 2 suggestions

9529724

Co-authored-by: Brian Chen <ToucheSir@users.noreply.github.com>

mcabbott commented Dec 1, 2022

View reviewed changes

docs/src/index.md Outdated Show resolved Hide resolved

mcabbott added 4 commits December 1, 2022 15:21

Update docs/src/index.md

d4c177d

add terminology note

e1e83c4

remove example functions from headings

821d8f2

fixup

10a50af

ToucheSir approved these changes Dec 8, 2022

View reviewed changes

mcabbott merged commit 815deaa into master Dec 8, 2022

mcabbott deleted the doc_sections3 branch December 8, 2022 03:49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Move doc sections to "guide" + "reference" #2115

Move doc sections to "guide" + "reference" #2115

mcabbott commented Nov 19, 2022 •

edited

Loading

github-actions bot commented Nov 19, 2022

This comment was marked as off-topic.

ToucheSir commented Nov 29, 2022

mcabbott commented Nov 29, 2022 •

edited

Loading

mcabbott Nov 29, 2022

mcabbott Nov 29, 2022

mcabbott Nov 29, 2022

mcabbott Nov 29, 2022

ToucheSir Dec 1, 2022

mcabbott Dec 1, 2022

ToucheSir Dec 2, 2022

mcabbott Dec 2, 2022

ToucheSir Dec 1, 2022

mcabbott Dec 1, 2022 •

edited

Loading

ToucheSir Dec 2, 2022

mcabbott Dec 8, 2022

ToucheSir Dec 8, 2022

mcabbott Dec 8, 2022


		* [SimpleChains.jl](https://github.com/PumasAI/SimpleChains.jl) is focused on making small, simple, CPU-based, neural networks fast. Uses [LoopVectorization.jl](https://github.com/JuliaSIMD/LoopVectorization.jl). (Was `FastChain` in DiffEqFlux.jl)

		* [Knet.jl](https://github.com/denizyuret/Knet.jl) is a neural network library built around [AutoGrad.jl](https://github.com/denizyuret/AutoGrad.jl), with beautiful documentation.

Move doc sections to "guide" + "reference" #2115

Move doc sections to "guide" + "reference" #2115

Conversation

mcabbott commented Nov 19, 2022 • edited Loading

Edit, more comments:

github-actions bot commented Nov 19, 2022

This comment was marked as off-topic.

ToucheSir commented Nov 29, 2022

mcabbott commented Nov 29, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mcabbott Dec 1, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mcabbott commented Nov 19, 2022 •

edited

Loading

mcabbott commented Nov 29, 2022 •

edited

Loading

mcabbott Dec 1, 2022 •

edited

Loading