Documentation tweaks

Author: Johannes Ballé

README.md

@@ -1,44 +1,45 @@
-This package contains data compression ops and layers for TensorFlow.
-
-# Documentation
-
-All documentation is hosted at https://tensorflow.github.io/compression.
-
-Refer to [the API documentation](https://tensorflow.github.io/compression/docs/api_docs/python/tfc.html)
-for a complete description of the Keras layers and TensorFlow ops this package
-implements.
-
-There's also an introduction to our `EntropyBottleneck` class
-[here](https://tensorflow.github.io/compression/docs/entropy_bottleneck.html),
-and a description of the range coding operators
-[here](https://tensorflow.github.io/compression/docs/range_coding.html).
-
-# Google group
-
-For usage questions and discussions, please head over to our
-[Google group](https://groups.google.com/forum/#!forum/tensorflow-compression).
+This project contains data compression ops and layers for TensorFlow. The
+project website is at https://tensorflow.github.io/compression.
 
 # Quick start
 
 **Please note**: You need TensorFlow 1.9 (or the master branch as of May 2018)
 or later installed.
 
+Clone the repository to a filesystem location of your choice, or download the
+ZIP file and unpack it. Then include the root directory in your `PYTHONPATH`
+environment variable:
+
+```bash
+cd <target directory>
+git clone https://github.com/tensorflow/compression.git tensorflow_compression
+export PYTHONPATH="$PWD/tensorflow_compression:$PYTHONPATH"
+```
+
 To make sure the library imports succeed, try running the unit tests:
 
 ```bash
+cd tensorflow_compression
 for i in tensorflow_compression/python/*/*_test.py; do
   python $i
 done
 ```
 
+We recommend importing the library from your Python code as follows:
+
+```python
+import tensorflow as tf
+import tensorflow_compression as tfc
+```
+
 ## Example model
 
 The [examples directory](https://github.com/tensorflow/compression/tree/master/examples)
 directory contains an implementation of the image compression model described
 in:
 
-> J. Ballé, V. Laparra, E. P. Simoncelli:
-> "End-to-end optimized image compression"
+> "End-to-end optimized image compression"<br />
+> J. Ballé, V. Laparra, E. P. Simoncelli<br />
 > https://arxiv.org/abs/1611.01704
 
 To see a list of options, change to the directory and run:
@@ -49,14 +50,28 @@ python bls2017.py -h
 
 To train the model, you need to supply it with a dataset of RGB training images.
 They should be provided in PNG format and must all have the same shape.
-Following training, the python script can be used to compress and decompress
+Following training, the Python script can be used to compress and decompress
 images as follows:
 
 ```bash
 python bls2017.py [options] compress original.png compressed.bin
 python bls2017.py [options] decompress compressed.bin reconstruction.png
 ```
 
+# Help & documentation
+
+For usage questions and discussions, please head over to our
+[Google group](https://groups.google.com/forum/#!forum/tensorflow-compression).
+
+Refer to [the API documentation](https://tensorflow.github.io/compression/docs/api_docs/python/tfc.html)
+for a complete description of the Keras layers and TensorFlow ops this package
+implements.
+
+There's also an introduction to our `EntropyBottleneck` class
+[here](https://tensorflow.github.io/compression/docs/entropy_bottleneck.html),
+and a description of the range coding operators
+[here](https://tensorflow.github.io/compression/docs/range_coding.html).
+
 # Authors
 Johannes Ballé (github: [jonycgn](https://github.com/jonycgn)),
 Sung Jin Hwang (github: [ssjhv](https://github.com/ssjhv)), and

docs/api_docs/python/tfc/EntropyBottleneck.md

@@ -76,11 +76,9 @@ The layer implements a flexible probability density model to estimate entropy
 of its input tensor, which is described in the appendix of the paper (please
 cite the paper if you use this code for scientific work):
 
-"Variational image compression with a scale hyperprior"
-
-Johannes Ballé, David Minnen, Saurabh Singh, Sung Jin Hwang, Nick Johnston
-
-https://arxiv.org/abs/1802.01436
+> "Variational image compression with a scale hyperprior"<br />
+> J. Ballé, D. Minnen, S. Singh, S. J. Hwang, N. Johnston<br />
+> https://arxiv.org/abs/1802.01436
 
 The layer assumes that the input tensor is at least 2D, with a batch dimension
 at the beginning and a channel dimension as specified by `data_format`. The

docs/api_docs/python/tfc/GDN.md

@@ -58,18 +58,14 @@ Generalized divisive normalization layer.
 
 Based on the papers:
 
-  "Density Modeling of Images using a Generalized Normalization
-  Transformation"
-
-  Johannes Ballé, Valero Laparra, Eero P. Simoncelli
-
-  https://arxiv.org/abs/1511.06281
-
-  "End-to-end Optimized Image Compression"
-
-  Johannes Ballé, Valero Laparra, Eero P. Simoncelli
-
-  https://arxiv.org/abs/1611.01704
+> "Density modeling of images using a generalized normalization
+> transformation"<br />
+> J. Ballé, V. Laparra, E.P. Simoncelli<br />
+> https://arxiv.org/abs/1511.06281
+
+> "End-to-end optimized image compression"<br />
+> J. Ballé, V. Laparra, E.P. Simoncelli<br />
+> https://arxiv.org/abs/1611.01704
 
 Implements an activation function that is essentially a multivariate
 generalization of a particular sigmoid-type function:

docs/api_docs/python/tfc/SignalConv1D.md

@@ -88,15 +88,17 @@ In general, the outputs are equivalent to a composition of:
 5. a pointwise nonlinearity (if `activation is not None`)
 
 For more information on what the difference between convolution and cross
-correlation is, see https://en.wikipedia.org/wiki/Convolution and
-https://en.wikipedia.org/wiki/Cross-correlation. Note that the distinction
-between convolution and cross correlation is occasionally blurred (one may use
-convolution as an umbrella term for both). For a discussion of
-up-/downsampling, see https://en.wikipedia.org/wiki/Upsampling and
-https://en.wikipedia.org/wiki/Decimation_(signal_processing). A more in-depth
-treatment of all of these operations can be found in:
-
-  Oppenheim, Schafer, Buck: Discrete-Time Signal Processing (Prentice Hall)
+correlation is, see [this](https://en.wikipedia.org/wiki/Convolution) and
+[this](https://en.wikipedia.org/wiki/Cross-correlation) Wikipedia article,
+respectively. Note that the distinction between convolution and cross
+correlation is occasionally blurred (one may use convolution as an umbrella
+term for both). For a discussion of up-/downsampling, refer to the articles
+about [upsampling](https://en.wikipedia.org/wiki/Upsampling) and
+[decimation](https://en.wikipedia.org/wiki/Decimation_(signal_processing)). A
+more in-depth treatment of all of these operations can be found in:
+
+> "Discrete-Time Signal Processing"<br />
+> Oppenheim, Schafer, Buck (Prentice Hall)
 
 For purposes of this class, the center position of a kernel is always
 considered to be at `K // 2`, where `K` is the support length of the kernel.

docs/api_docs/python/tfc/SignalConv2D.md

@@ -88,15 +88,17 @@ In general, the outputs are equivalent to a composition of:
 5. a pointwise nonlinearity (if `activation is not None`)
 
 For more information on what the difference between convolution and cross
-correlation is, see https://en.wikipedia.org/wiki/Convolution and
-https://en.wikipedia.org/wiki/Cross-correlation. Note that the distinction
-between convolution and cross correlation is occasionally blurred (one may use
-convolution as an umbrella term for both). For a discussion of
-up-/downsampling, see https://en.wikipedia.org/wiki/Upsampling and
-https://en.wikipedia.org/wiki/Decimation_(signal_processing). A more in-depth
-treatment of all of these operations can be found in:
-
-  Oppenheim, Schafer, Buck: Discrete-Time Signal Processing (Prentice Hall)
+correlation is, see [this](https://en.wikipedia.org/wiki/Convolution) and
+[this](https://en.wikipedia.org/wiki/Cross-correlation) Wikipedia article,
+respectively. Note that the distinction between convolution and cross
+correlation is occasionally blurred (one may use convolution as an umbrella
+term for both). For a discussion of up-/downsampling, refer to the articles
+about [upsampling](https://en.wikipedia.org/wiki/Upsampling) and
+[decimation](https://en.wikipedia.org/wiki/Decimation_(signal_processing)). A
+more in-depth treatment of all of these operations can be found in:
+
+> "Discrete-Time Signal Processing"<br />
+> Oppenheim, Schafer, Buck (Prentice Hall)
 
 For purposes of this class, the center position of a kernel is always
 considered to be at `K // 2`, where `K` is the support length of the kernel.

docs/api_docs/python/tfc/SignalConv3D.md

@@ -88,15 +88,17 @@ In general, the outputs are equivalent to a composition of:
 5. a pointwise nonlinearity (if `activation is not None`)
 
 For more information on what the difference between convolution and cross
-correlation is, see https://en.wikipedia.org/wiki/Convolution and
-https://en.wikipedia.org/wiki/Cross-correlation. Note that the distinction
-between convolution and cross correlation is occasionally blurred (one may use
-convolution as an umbrella term for both). For a discussion of
-up-/downsampling, see https://en.wikipedia.org/wiki/Upsampling and
-https://en.wikipedia.org/wiki/Decimation_(signal_processing). A more in-depth
-treatment of all of these operations can be found in:
-
-  Oppenheim, Schafer, Buck: Discrete-Time Signal Processing (Prentice Hall)
+correlation is, see [this](https://en.wikipedia.org/wiki/Convolution) and
+[this](https://en.wikipedia.org/wiki/Cross-correlation) Wikipedia article,
+respectively. Note that the distinction between convolution and cross
+correlation is occasionally blurred (one may use convolution as an umbrella
+term for both). For a discussion of up-/downsampling, refer to the articles
+about [upsampling](https://en.wikipedia.org/wiki/Upsampling) and
+[decimation](https://en.wikipedia.org/wiki/Decimation_(signal_processing)). A
+more in-depth treatment of all of these operations can be found in:
+
+> "Discrete-Time Signal Processing"<br />
+> Oppenheim, Schafer, Buck (Prentice Hall)
 
 For purposes of this class, the center position of a kernel is always
 considered to be at `K // 2`, where `K` is the support length of the kernel.

docs/api_docs/python/tfc/same_padding_for_kernel.md

@@ -14,8 +14,8 @@ tfc.same_padding_for_kernel(
 
 Determine correct amount of padding for `same` convolution.
 
-To implement `same` convolutions, we first pad the image, and then perform a
-`valid` convolution or correlation. Given the kernel shape, this function
+To implement `'same'` convolutions, we first pad the image, and then perform a
+`'valid'` convolution or correlation. Given the kernel shape, this function
 determines the correct amount of padding so that the output of the convolution
 or correlation is the same size as the pre-padded input.
 
@@ -24,8 +24,8 @@ or correlation is the same size as the pre-padded input.
 * <b>`shape`</b>: Shape of the convolution kernel (without the channel dimensions).
 * <b>`corr`</b>: Boolean. If `True`, assume cross correlation, if `False`, convolution.
 * <b>`strides_up`</b>: If this is used for an upsampled convolution, specify the
-    strides here. (For downsampled convolutions, specify (1, 1): in that case,
-    the strides don't matter.)
+    strides here. (For downsampled convolutions, specify `(1, 1)`: in that
+    case, the strides don't matter.)
 
 
 #### Returns:

docs/entropy_bottleneck.md

@@ -19,8 +19,8 @@ The layer implements a flexible probability density model to estimate entropy,
 which is described in the appendix of the paper (please cite the paper if you
 use this code for scientific work):
 
-> J. Ballé, D. Minnen, S. Singh, S. J. Hwang, N. Johnston:
-> "Variational image compression with a scale hyperprior"
+> "Variational image compression with a scale hyperprior"<br />
+> J. Ballé, D. Minnen, S. Singh, S. J. Hwang, N. Johnston<br />
 > https://arxiv.org/abs/1802.01436
 
 The layer assumes that the input tensor is at least 2D, with a batch dimension

tensorflow_compression/python/layers/entropy_models.py

@@ -57,11 +57,9 @@ class EntropyBottleneck(base_layer.Layer):
   of its input tensor, which is described in the appendix of the paper (please
   cite the paper if you use this code for scientific work):
 
-  "Variational image compression with a scale hyperprior"
-
-  Johannes Ballé, David Minnen, Saurabh Singh, Sung Jin Hwang, Nick Johnston
-
-  https://arxiv.org/abs/1802.01436
+  > "Variational image compression with a scale hyperprior"<br />
+  > J. Ballé, D. Minnen, S. Singh, S. J. Hwang, N. Johnston<br />
+  > https://arxiv.org/abs/1802.01436
 
   The layer assumes that the input tensor is at least 2D, with a batch dimension
   at the beginning and a channel dimension as specified by `data_format`. The

tensorflow_compression/python/layers/gdn.py

@@ -43,18 +43,14 @@ class GDN(base.Layer):
 
   Based on the papers:
 
-    "Density Modeling of Images using a Generalized Normalization
-    Transformation"
-
-    Johannes Ballé, Valero Laparra, Eero P. Simoncelli
-
-    https://arxiv.org/abs/1511.06281
-
-    "End-to-end Optimized Image Compression"
-
-    Johannes Ballé, Valero Laparra, Eero P. Simoncelli
-
-    https://arxiv.org/abs/1611.01704
+  > "Density modeling of images using a generalized normalization
+  > transformation"<br />
+  > J. Ballé, V. Laparra, E.P. Simoncelli<br />
+  > https://arxiv.org/abs/1511.06281
+
+  > "End-to-end optimized image compression"<br />
+  > J. Ballé, V. Laparra, E.P. Simoncelli<br />
+  > https://arxiv.org/abs/1611.01704
 
   Implements an activation function that is essentially a multivariate
   generalization of a particular sigmoid-type function: