Add a quick start example, and change some headings #2069

mcabbott · 2022-09-27T02:52:46Z

[Replaces #2068]

This wants to change the start of the docs, so that "Getting Started" has (after the index page) two paths: A fast one (for people who know about neural nets, just not Flux) and a slow one (introducing linear regressing, parameters, etc). The slow one was called "Overview" before.

The fast one is new. I'm not sure it's the optimal example, maybe MNIST can be done about as compactly? It aims to fit on one screen & show you all the main moving parts.

Re-reading "Overview", it's nicer than I remembered. I'm not entirely sure it should live in a different section to the next one, "Basics" (which I call "Gradients and Layers" here). So I moved the second "Basics" one into "Getting Started" too. (I do think they need better titles.)

I'm not precisely sure how this intersects with #2036, #2021, #2016. Those may replace text in some sections, to make the slow path even more detailed, or to upgrade the "Basics" section. Or maybe we want a tutorials section in the docs, which replaces the one in the website?

github-actions · 2022-09-27T02:54:13Z

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

codecov-commenter · 2022-09-27T03:38:12Z

Codecov Report

Base: 86.26% // Head: 86.26% // No change to project coverage 👍

Coverage data is based on head (da5fb4f) compared to base (dfc5a7e).
Patch has no changes to coverable lines.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2069   +/-   ##
=======================================
  Coverage   86.26%   86.26%           
=======================================
  Files          18       18           
  Lines        1361     1361           
=======================================
  Hits         1174     1174           
  Misses        187      187

Impacted Files	Coverage Δ
src/outputsize.jl	`87.17% <ø> (ø)`

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

ToucheSir · 2022-09-27T03:44:09Z

I like the proposed structure here. Could the "Fitting a Line" page mention "linear regression" somewhere to contextualize the problem and help with keyword searches? Haven't looked at the other docs changes yet.

mcabbott · 2022-09-27T15:06:05Z

One unhappy feature is that we have a bit of a random mix of sections describing stuff in words, and sections which are more API listings.

Maybe the ought to be marked somehow, something like this?

Perhaps we also need to take a pass and move some of the more scattered docstrings from "descriptive" sections to "listing" sections.

Edit: done in bad3011, see what you think. This also re-orders sections a bit... maybe loss functions & regularisation are part of training, right?

Maybe all the sections named for packages should name a function from that package, so that you have some idea why you may want to open that section, too.

mcabbott · 2022-09-29T01:42:16Z

docs/src/assets/flux.css

+article .docstring pre {
+  /* cancel negative spacing inside a docstring, as it collides with outer box */
+  margin-left: 0em;
+  margin-right: 0em;


Note the overlapping boxes here, on master:

Maybe the negative space should just be removed entirely.

I'm all for removing the negative spacing. At the very least, it should be opt-in instead of opt-out.

Come to think of it, is there a need for this stylesheet at all? Looking through some SciML package docs, any deviations from the default Documenter theme seem minimal and thus the maintenance overhead not very justifiable.

I do think it's nice if distinct packages look a little different, if only to help you remember which tab is which... here this seems to mean being a bit green.

Would be better if all FluxML docs pulled the style sheet from one place though. ChainRules et al moved theirs to a package https://github.com/JuliaDiff/DocThemeIndigo.jl but I'm not volunteering to set that up.

The one big visual change which would be nice would be to unify the website and the docs, like e.g. https://turing.ml/v0.21/docs/using-turing/quick-start . Maybe we can steal things from https://github.com/TuringLang/turinglang.github.io

03eba13 removes all negative spacing, looks fine.

mcabbott · 2022-10-08T13:45:18Z

docs/src/index.md

-* **Play nicely with others**. Flux works well with Julia libraries from [data frames](https://github.com/JuliaComputing/JuliaDB.jl) and [images](https://github.com/JuliaImages/Images.jl) to [differential equation solvers](https://github.com/JuliaDiffEq/DifferentialEquations.jl), so you can easily build complex data processing pipelines that integrate Flux models.
+* **Play nicely with others**. Flux works well with Julia libraries from [images](https://github.com/JuliaImages/Images.jl) to [differential equation solvers](https://github.com/JuliaDiffEq/DifferentialEquations.jl), so you can easily build complex data processing pipelines that integrate Flux models.


In fact https://github.com/JuliaData/JuliaDB.jl is long-dead. Should anything else be highlighted?

My vote is to make this intro shorter if possible, it's not all that helpful.

Does it make any sense to s/diffeq/sciml/g for this point?

Probably! Link does still work.

mcabbott · 2022-10-08T13:47:35Z

docs/src/models/basics.md

-## Layer helpers
+## Layer Helpers

 Flux provides a set of helpers for custom layers, which you can enable by calling


In fact only one helper. Maybe this section made more sense long ago. Maybe it should include create_bias alla #2049?

Done in 98b4cd8

mcabbott · 2022-10-10T19:36:24Z

Shall we do this? It's not done but seems like a step forwards.

Biggish changes not mentioned in the top message are:

The "advanced.md" page about custom layers is moved to the tutorials. It's a bit of a random selection of examples, and perhaps could be tidied up, but I didn't try.
New page for destructure, plus Flux.modules, as they didn't fit well elsewhere
Adding 📚 to mark sections which contain API listings. I think moving text / docstrings to make every page more cleanly one or the other class would make this better.

Note that I didn't move any files, and thus the directory structure no longer matches the doc sections. We can move them once we are happy with the arrangement. Doing so will break links, though... I have added some explicit ID tags to titles, which I think are better than referring to the title text itself or the file name. But I have not attempted to go through and update all links.

I think the next steps after this are

to re-organise the training / regularization / optimisers docs. But these are coupled to the move away from implicit parameters.
to start moving other tutorials here from the website. Coupled to work on the website.

mcabbott · 2022-10-11T00:29:22Z

Adding 📚 to mark sections which contain API listings.

An alternative here would be to re-order sections into Guide / Reference. Maybe better? But right now the division isn't quite clean enough, IMO... the optimisers / training sections especially are a bit tangled.

Saransh-cpp

Thank you for this, @mcabbott! I do like the idea of separating out the API reference from the guide, but this can be taken up in another PR (if this PR is getting too large). Some minor comments below -

docs/src/data/mlutils.md

Saransh-cpp · 2022-10-11T13:31:45Z

docs/src/models/basics.md

-For some more helpful tricks, including parameter freezing, please checkout the [advanced usage guide](advanced.md).
+```@docs
+Functors.@functor
+Flux.create_bias


Reminds me of #2049. We can get rid of _create_bias now that create_bias is a public API. Can be handled in another PR!

docs/src/models/quickstart.md

Co-authored-by: Saransh Chopra <saransh0701@gmail.com>

mcabbott · 2022-10-11T14:53:52Z

I think the hurdles to separating Guide / Reference are

that the order of reference starts to seem completely random, is there a better way? maybe moving all the "foreign" pages to "Reference, II" section would help?
that quite a few sections currently are half in each camp, training / optimisers etc. But these will change for 0.14 anyway.

Anyway, small steps forwards...

Brings us in line with changes on the Flux side: FluxML/Flux.jl#2069

mcabbott mentioned this pull request Sep 27, 2022

[Discussion]: Revamped Getting Started guide #2012

Closed

mcabbott added the documentation label Sep 27, 2022

mcabbott mentioned this pull request Sep 27, 2022

Add a quick start example ... [moved] #2068

Closed

mcabbott force-pushed the doc_sections2 branch from a026e5c to f3c68f6 Compare September 27, 2022 14:04

mcabbott force-pushed the doc_sections2 branch from f3c68f6 to b7389b5 Compare September 27, 2022 15:41

mcabbott force-pushed the doc_sections2 branch from f8d5cd0 to 45735b9 Compare October 8, 2022 13:41

mcabbott commented Oct 8, 2022

View reviewed changes

mcabbott added 19 commits October 10, 2022 14:34

add quickstart page

a3d3790

tidy welcome page

fa03168

adjust folders, and some headings

616ea1c

move one page to first section

9594d86

tweaks

5a619c8

say linear regression somewhere, just not in the title

475a499

tweaks

c5d699a

add emoji for API, re-order

e96717d

also mention function names

14f129d

activations intro

429be47

move destructure to a new file, along with modules

3ab5576

tweaks

1c10ade

tweaks

cb8880f

sciml link

7c026e1

less negative spacing

9794800

rm all negative spacing

de023c2

better Layer Helpers section

5efcdc1

move Custom Layers to Tutorials section

66d7dc4

fixup

23baf23

mcabbott requested a review from Saransh-cpp October 10, 2022 19:36

mcabbott force-pushed the doc_sections2 branch from da5fb4f to 23baf23 Compare October 10, 2022 21:46

Saransh-cpp approved these changes Oct 11, 2022

View reviewed changes

mcabbott and others added 2 commits October 11, 2022 10:50

Apply 3 suggestions

166243d

Co-authored-by: Saransh Chopra <saransh0701@gmail.com>

one more

56d950a

Co-authored-by: Saransh Chopra <saransh0701@gmail.com>

mcabbott merged commit b08cb67 into master Oct 11, 2022

mcabbott deleted the doc_sections2 branch October 11, 2022 14:58

mcabbott mentioned this pull request Oct 13, 2022

Remove negative space from css FluxML/Optimisers.jl#111

Merged

ToucheSir added a commit to FluxML/NNlib.jl that referenced this pull request Oct 22, 2022

Remove negative margin in docs CSS

371adb7

Brings us in line with changes on the Flux side: FluxML/Flux.jl#2069

ToucheSir mentioned this pull request Oct 22, 2022

Remove negative margin in docs CSS FluxML/NNlib.jl#437

Merged

This was referenced Nov 16, 2022

Documentation overhaul roadmap #2105

Open

Re-organise "built-in layers" section #2112

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a quick start example, and change some headings #2069

Add a quick start example, and change some headings #2069

mcabbott commented Sep 27, 2022 •

edited

github-actions bot commented Sep 27, 2022

codecov-commenter commented Sep 27, 2022 •

edited

ToucheSir commented Sep 27, 2022

mcabbott commented Sep 27, 2022 •

edited

mcabbott Sep 29, 2022

ToucheSir Oct 8, 2022

mcabbott Oct 8, 2022

mcabbott Oct 10, 2022

mcabbott Oct 8, 2022

ToucheSir Oct 8, 2022

mcabbott Oct 8, 2022

mcabbott Oct 10, 2022

mcabbott Oct 8, 2022

mcabbott Oct 10, 2022

mcabbott commented Oct 10, 2022 •

edited

mcabbott commented Oct 11, 2022

Saransh-cpp left a comment

Saransh-cpp Oct 11, 2022

mcabbott commented Oct 11, 2022 •

edited

		* Play nicely with others. Flux works well with Julia libraries from [data frames](https://github.com/JuliaComputing/JuliaDB.jl) and [images](https://github.com/JuliaImages/Images.jl) to [differential equation solvers](https://github.com/JuliaDiffEq/DifferentialEquations.jl), so you can easily build complex data processing pipelines that integrate Flux models.
		* Play nicely with others. Flux works well with Julia libraries from [images](https://github.com/JuliaImages/Images.jl) to [differential equation solvers](https://github.com/JuliaDiffEq/DifferentialEquations.jl), so you can easily build complex data processing pipelines that integrate Flux models.

Add a quick start example, and change some headings #2069

Add a quick start example, and change some headings #2069

Conversation

mcabbott commented Sep 27, 2022 • edited

github-actions bot commented Sep 27, 2022

codecov-commenter commented Sep 27, 2022 • edited

Codecov Report

ToucheSir commented Sep 27, 2022

mcabbott commented Sep 27, 2022 • edited

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

Choose a reason for hiding this comment

mcabbott commented Oct 10, 2022 • edited

mcabbott commented Oct 11, 2022

Saransh-cpp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mcabbott commented Oct 11, 2022 • edited

mcabbott commented Sep 27, 2022 •

edited

codecov-commenter commented Sep 27, 2022 •

edited

mcabbott commented Sep 27, 2022 •

edited

mcabbott commented Oct 10, 2022 •

edited

mcabbott commented Oct 11, 2022 •

edited