A wide pass on docs #657

avital · 2020-11-20T16:32:00Z

Added an autoencoder example to README to showcase modules with
multiple methods
Remove FAQ (it was all on the old API) -- we can consider bringing
it back but best to just link to GitHub discussions if possible?
Mark flax.nn as deprecated in more places and make it less visible
Add deprecation notice in examples/README. (I will later remove the
directory entirely but I wanted to separate those)
Small adjustments

1. Added an autoencoder example to README to showcase modules with multiple methods 2. Remove FAQ (it was all on the old API) -- we can consider bringing it back but best to just link to GitHub discussions if possible? 3. Mark `flax.nn` as deprecated in more places and make it less visible 4. Add deprecation notice in examples/README. (I will later remove the directory entirely but I wanted to separate those) 5. Small adjustments

BertrandRdp

LGTM, that's a great refresh

codecov-io · 2020-11-20T16:47:18Z

Codecov Report

Merging #657 (5e0ec16) into master (fbd3aec) will increase coverage by 0.08%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master     #657      +/-   ##
==========================================
+ Coverage   80.59%   80.67%   +0.08%     
==========================================
  Files          56       56              
  Lines        4241     4269      +28     
==========================================
+ Hits         3418     3444      +26     
- Misses        823      825       +2

Impacted Files	Coverage Δ
flax/linen/__init__.py	`100.00% <100.00%> (ø)`
flax/core/variables.py	`0.00% <0.00%> (-100.00%)`	⬇️
flax/optim/rmsprop.py	`100.00% <0.00%> (ø)`
flax/linen/attention.py	`96.29% <0.00%> (ø)`
flax/linen/dotgetter.py	`70.21% <0.00%> (ø)`
flax/linen/linear.py	`99.45% <0.00%> (+<0.01%)`	⬆️
flax/nn/base.py	`92.46% <0.00%> (+0.01%)`	⬆️
flax/optim/dynamic_scale.py	`95.55% <0.00%> (+0.10%)`	⬆️
flax/optim/base.py	`81.56% <0.00%> (+0.10%)`	⬆️
... and 6 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update fbd3aec...5e0ec16. Read the comment docs.

avital · 2020-11-20T17:06:25Z

examples/README.md

-
-## Official examples maintained by the Flax core team
-
-This folder contains a collection of examples of implementations of various architectures and training procedures.


Hi @andsteing -- I noticed that much of the content from this README hasn't been ported to our new documentation. Specifically:

The "example matrix" diagram

The description of goals for our examples

Links and suggestions from the broader ecosystem (we may want to reach out to the package authors linked to from here so that all the packages are ported to Linen).

Was there an intention to add linen_examples/README.md, or to add back some of this content directly into RTD? Or something else? Happy to help, just wanted to see if there had been prior thinking about this.

I think I will first update and move to linen_examples/README.md. Not sure if we want to have it in RTD or keep it as a README. Let's discuss this and move it in a second step if we decide for RTD.

Removed in #669

andsteing

Nice change !

andsteing · 2020-11-23T15:05:56Z

examples/README.md

-| [seq2seq](seq2seq/README.md) | LSTM encoder/decoder for completing `42+1234=` sequences | On the fly data generation, LSTM state handling, simple code |
-| [vae](vae/README.md) | Variational auto-encoder for binarized MNIST images | Tfds `binarized_mnist`, vmap, simple code |
-| [wmt](wmt/README.md) | Transformer for translating en/de | Multi host SPMD, tfds `wmt1{4,7}_translate`, SentencePiece tokenization, checkpointing, dynamic bucketing, attention cache, packed sequences, recipe for TPU training on GCP |
+You've caught us mid-way through our chrysallis! This directory


:)
it's one "s", though

andsteing · 2020-11-23T15:09:06Z

README.md

@@ -10,20 +10,18 @@ Please check our [full documentation](https://flax.readthedocs.io/) website to l

 **NOTE**: Flax is in use by a growing community
 of researchers and engineers at Google who happily use Flax for their
-daily research. The new Flax ["Linen" module API](https://github.com/google/flax/tree/master/flax/linen) is now stable and we recommend it for all new projects. The old `flax.nn` API will be deprecated. Please report
+daily research. The new Flax ["Linen" module API](https://github.com/google/flax/tree/master/flax/linen/README.md) is now stable and we recommend it for all new projects. The old `flax.nn` API will be deprecated. Please report


A general remark : I'm a big fan of wrapped paragraphs.

One of many advantages is that vscode side by side review is much easier when paragraphs are wrapped (due to microsoft/vscode#11387 )

andsteing · 2020-11-23T15:11:49Z

README.md

+We provide three examples using the Flax API: a simple multi-layer perceptron, a CNN and an auto-encoder. 
+
+To learn more about the `Module` abstraction, please check our [docs](https://flax.readthedocs.io/), or visit our
+[patterns](https://flax.readthedocs.io/en/latest/patterns/flax_patterns.html) page for additional concrete demonstrations of best practices.


what about linking to
https://github.com/google/flax/blob/master/docs/notebooks/linen_intro.ipynb

people seem to have liked that notebook.

andsteing · 2020-11-23T15:21:10Z

README.md

+```py
+class AutoEncoder(Module):
+  encoder_widths: Iterable
+  decoder_widths: Iterable


MLP expects Sequence[int]

andsteing · 2020-11-23T15:21:12Z

README.md

@@ -79,6 +76,30 @@ class CNN(nn.Module):
    return x
 ```

+```py
+class AutoEncoder(Module):
+  encoder_widths: Iterable


MLP expects Sequence[int]

andsteing · 2020-11-23T15:21:19Z

README.md

+class AutoEncoder(Module):
+  encoder_widths: Iterable
+  decoder_widths: Iterable
+  input_shape: Tuple = None


why not Tuple[int] ?

you're right

andsteing · 2020-11-23T15:25:08Z

README.md

+    return self.decode(self.encode(x))
+
+  def encode(self, x):
+    assert x.shape[-len(self.input_shape):] == self.input_shape


shouldn't we check

assert x.shape[1:] == self.input_shape

if there are more than 1 dimensions in front of the expected self.input_shape, they will be flattened in the next line, and not maintained in the return value from decode()

(e.g. if input_shape=(3, 4) and x.shape=(5,10,3,4) then the return value from decode() will have shape=(50,3,4))

good catch.

andsteing · 2020-11-23T15:29:18Z

docs/flax.linen.rst

@@ -3,7 +3,9 @@ flax.linen package
 ==================

 .. currentmodule:: flax.linen
-.. automodule:: flax.linen
+
+Linen is the Flax Module system. Read more about our design goals in the `Linen README <https://github.com/google/flax/blob/master/flax/linen/README.md>`_.


while reading through that file: what happened to the "various advanced use-cases" link?
https://github.com/google/flax/tree/master/linen_examples/core_design_test

It's still there? see the bottom -- ""Design tests" used to ensure that our "functional core" supports various advanced use-cases, and that the mostly-syntactic-sugar Module abstraction doesn't get in the way"

andsteing · 2020-11-23T15:43:20Z

docs/index.rst

@@ -6,20 +6,12 @@
 Flax documentation
 ==================

-Flax is a neural network library for JAX that is designed for flexibility and
+Flax is a neural network library and ecosystem for JAX that is designed for flexibility. Flax 


Can you reformat this paragraph?
(vscode : install Rewrap and then Alt-Q)

done (I used Emacs alt-q for this, hope you're OK with that)

avital requested review from BertrandRdp and andsteing November 20, 2020 16:32

avital assigned andsteing Nov 20, 2020

google-cla bot added the cla: yes label Nov 20, 2020

Update Linen module API link to README rather than directory

8e9dea3

BertrandRdp approved these changes Nov 20, 2020

View reviewed changes

avital commented Nov 20, 2020

View reviewed changes

andsteing reviewed Nov 23, 2020

View reviewed changes

Respond to @andstein's comments

5e0ec16

andsteing approved these changes Dec 2, 2020

View reviewed changes

copybara-service bot merged commit 567dcfc into google:master Dec 2, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

A wide pass on docs #657

A wide pass on docs #657

avital commented Nov 20, 2020

BertrandRdp left a comment

codecov-io commented Nov 20, 2020 •

edited

Loading

avital Nov 20, 2020

andsteing Nov 23, 2020

andsteing Dec 2, 2020

andsteing left a comment

andsteing Nov 23, 2020

avital Dec 2, 2020

andsteing Nov 23, 2020

avital Dec 2, 2020

andsteing Nov 23, 2020

avital Dec 2, 2020

andsteing Nov 23, 2020

avital Dec 2, 2020

andsteing Nov 23, 2020

andsteing Nov 23, 2020

avital Dec 2, 2020

andsteing Nov 23, 2020

avital Dec 2, 2020

andsteing Nov 23, 2020

avital Dec 2, 2020

andsteing Nov 23, 2020

avital Dec 2, 2020


		## Official examples maintained by the Flax core team

		This folder contains a collection of examples of implementations of various architectures and training procedures.

A wide pass on docs #657

A wide pass on docs #657

Conversation

avital commented Nov 20, 2020

BertrandRdp left a comment

Choose a reason for hiding this comment

codecov-io commented Nov 20, 2020 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andsteing left a 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

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

codecov-io commented Nov 20, 2020 •

edited

Loading