add bazel command to generate API docs (#206)

* ENH: integrate with bazel

* DOC: how to install dependencies

* FIX: tf.function and __version__

* DOC: use tfa as short name

* DOC: add tutorial in details

Author: facaiy

.gitignore

@@ -35,4 +35,8 @@ wheels/
 # Build
 /.bazelrc
 /bazel-*
-/artifacts
+/artifacts
+
+# Addons
+.*
+/docs/

BUILD

@@ -6,13 +6,5 @@ sh_binary(
         "MANIFEST.in",
         "setup.py",
         "//tensorflow_addons",
-        "//tensorflow_addons/activations",
-        "//tensorflow_addons/image",
-        "//tensorflow_addons/layers",
-        "//tensorflow_addons/losses",
-        "//tensorflow_addons/optimizers",
-        "//tensorflow_addons/rnn",
-        "//tensorflow_addons/seq2seq",
-        "//tensorflow_addons/text",
     ],
 )

tensorflow_addons/BUILD

@@ -8,4 +8,14 @@ py_library(
         "__init__.py",
         "version.py",
     ],
+    deps = [
+        "//tensorflow_addons/activations",
+        "//tensorflow_addons/image",
+        "//tensorflow_addons/layers",
+        "//tensorflow_addons/losses",
+        "//tensorflow_addons/optimizers",
+        "//tensorflow_addons/rnn",
+        "//tensorflow_addons/seq2seq",
+        "//tensorflow_addons/text",
+    ],
 )

tools/docs/BUILD

@@ -0,0 +1,19 @@
+# Description:
+#   Doc generator
+
+licenses(["notice"])  # Apache 2.0
+
+exports_files(["LICENSE"])
+
+package(
+    default_visibility = ["//tensorflow_addons:__subpackages__"],
+)
+
+py_binary(
+    name = "build_docs",
+    srcs = ["build_docs.py"],
+    srcs_version = "PY2AND3",
+    deps = [
+        "//tensorflow_addons",
+    ],
+)

tools/docs/README.md

@@ -0,0 +1,20 @@
+Generate API documents
+
+```bash
+# Install dependencies:
+pip install -r doc_requirements.txt
+
+# Build tool:
+bazel build tools/docs:build_docs
+
+# Generate API doc:
+# Use current branch
+bazel-bin/tools/docs/build_docs --git_branch=$(git rev-parse --abbrev-ref HEAD)
+# or specified explicitly
+bazel-bin/tools/docs/build_docs --git_branch=master --output_dir=docs/api_docs/python/
+
+# Release API doc:
+git add -f doc/
+git commit -m "DOC: xxxxx"
+git push
+```

tools/docs/build_docs.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-""" Modified from the tfdocs example api reference docs generation script.
+"""Modified from the tfdocs example api reference docs generation script.
 
 This script generates API reference docs.
 
@@ -31,31 +31,47 @@
 from absl import app
 from absl import flags
 
-import tensorflow_addons
+import tensorflow_addons as tfa
+
 from tensorflow_docs.api_generator import generate_lib
+from tensorflow_docs.api_generator import parser
 from tensorflow_docs.api_generator import public_api
 
-PROJECT_SHORT_NAME = 'tfaddons'
+from tensorflow.python.util import tf_inspect
+
+# Use tensorflow's `tf_inspect`, which is aware of `tf_decorator`.
+parser.tf_inspect = tf_inspect
+
+PROJECT_SHORT_NAME = 'tfa'
 PROJECT_FULL_NAME = 'TensorFlow Addons'
-CODE_URL_PREFIX = 'https://github.com/tensorflow/addons/tree/master/tensorflow_addons'
 
 FLAGS = flags.FLAGS
 
+flags.DEFINE_string(
+    'git_branch',
+    default='master',
+    help='The name of the corresponding branch on github.')
+
 flags.DEFINE_string(
     'output_dir',
-    default='/addons/docs/api_docs/python/',
+    default='docs/api_docs/python/',
     help='Where to write the resulting docs to.')
 
 
 def main(argv):
     if argv[1:]:
         raise ValueError('Unrecognized arguments: {}'.format(argv[1:]))
 
+    code_url_prefix = ('https://github.com/tensorflow/addons/tree/'
+                       '{git_branch}/tensorflow_addons'.format(
+                           git_branch=FLAGS.git_branch))
+
     doc_generator = generate_lib.DocGenerator(
         root_title=PROJECT_FULL_NAME,
         # Replace `tensorflow_docs` with your module, here.
-        py_modules=[(PROJECT_SHORT_NAME, tensorflow_addons)],
-        code_url_prefix=CODE_URL_PREFIX,
+        py_modules=[(PROJECT_SHORT_NAME, tfa)],
+        code_url_prefix=code_url_prefix,
+        private_map={'tfa': ['__version__', 'utils', 'version']},
         # This callback cleans up a lot of aliases caused by internal imports.
         callbacks=[public_api.local_definitions_filter])
 

tools/docs/doc_requirements.txt

@@ -0,0 +1,2 @@
+git+https://github.com/tensorflow/docs
+pathlib