diff --git a/distributed_embeddings/python/layers/embedding.py b/distributed_embeddings/python/layers/embedding.py index 5378b4d..0175eb0 100644 --- a/distributed_embeddings/python/layers/embedding.py +++ b/distributed_embeddings/python/layers/embedding.py @@ -52,11 +52,11 @@ class Embedding(tf.keras.layers.Layer): the `embeddings` matrix (see `keras.constraints`). combiner (str): Reduction method, ['sum', 'mean'] or None. Default None. - When combiner is not None, supported input and their respectively output shape are: - N-D `Tensor`: `(d1,...,dn)`, output shape: `(d1,...,dn-1,output_dim)`, N >= 2 - 2-D `RaggedTensor`: `(batch_size, ragged_dim)`, output shape: `(batch_size, output_dim)` - 2-D `SparseTensor`: `(batch_size, max_hotness)`, output shape: `(batch_size, output_dim)` - Embedding picked from last input dimension will be reduced with given combiner. + When combiner is not None, supported input and their respectively output shape are: + N-D `Tensor`: `(d1,...,dn)`, output shape: `(d1,...,dn-1,output_dim)`, N >= 2 + 2-D `RaggedTensor`: `(batch_size, ragged_dim)`, output shape: `(batch_size, output_dim)` + 2-D `SparseTensor`: `(batch_size, max_hotness)`, output shape: `(batch_size, output_dim)` + Embedding picked from last input dimension will be reduced with given combiner. """ def __init__(self, diff --git a/docs/README.md b/docs/README.md new file mode 100755 index 0000000..5f5374e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,52 @@ +# Documentation + +This folder contains the scripts necessary to build the documentation. + +## Building the documentation + +1. To build the docs, start a container and mounting the root directory + of the repository into the container at the `/workspace` mount point: + + ```shell + docker run --rm -it --net=host \ + -u $(id -u):$(id -g) -v $(pwd):/workspace -w /workspace \ + nvcr.io/nvidia/merlin/merlin-tensorflow:nightly + ``` + +1. Build the software: + + ```shell + make all + ``` + +1. Install required documentation tools and extensions: + + ```shell + export HOME=/tmp + export PATH=$HOME/.local/bin:$PATH + python -m pip install -r docs/requirements-doc.txt + ``` + +1. Build the documentation: + + ```shell + export PYTHONPATH=$(python -c 'import site; print(site.getusersitepackages(), end="")') + make -C docs clean html + ``` + + > **Troubleshooting Tip** To get verbose output from the Sphinx build, run + > `make -C docs clean` and then run `sphinx-build -vv docs/source docs/build/html`. + > When Sphinx loads libraries, the verbose output shows the path for the library. + +The preceding command runs Sphinx in your shell and outputs to `docs/build/html/`. + +In a shell that is outside the container, start a simple HTTP server: + +`python -m http.server -d docs/build/html 8000` + +Then, navigate a web browser to the IP address or hostname of the host machine at port 8000: + +`https://localhost:8000` + +Now you can check if your docs edits formatted correctly, and read well. + diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt new file mode 100644 index 0000000..60fef35 --- /dev/null +++ b/docs/requirements-doc.txt @@ -0,0 +1,34 @@ +# docs +ipython==8.2.0 +Sphinx==3.5.4 +jinja2<3.1 +markupsafe==2.0.1 +natsort==8.1.0 +sphinx_rtd_theme +sphinx_markdown_tables +sphinx-multiversion@git+https://github.com/mikemckiernan/sphinx-multiversion.git@v0.3.0 +sphinxcontrib-copydirs@git+https://github.com/mikemckiernan/sphinxcontrib-copydirs.git@v0.3.3 +sphinx-external-toc<0.4 +myst-nb +linkify-it-py + +# smx +mergedeep<1.4 +docker<5.1 +PyGithub<1.56 +semver>=2,<3 + +# packages necessary to run tests and push PRs +# assumes requirements for nvtabular logic are already installed + +black==21.7b0 +click<8.1.0 +flake8==3.9.2 +isort==5.9.3 +pylint==2.7.4 +bandit==1.7.0 +flake8-nb==0.3.0 +pytest>=5 +pytest-cov>=2 +codespell +interrogate==1.5.0 diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css new file mode 100644 index 0000000..319ddff --- /dev/null +++ b/docs/source/_static/css/custom.css @@ -0,0 +1,34 @@ +.wy-nav-content { + margin: 0; + background: #fcfcfc; + padding-top: 40px; +} + +.wy-side-nav-search { + display: block; + width: 300px; + padding: .809em; + padding-top: 0.809em; + margin-bottom: .809em; + z-index: 200; + background-color: #2980b9; + text-align: center; + color: #fcfcfc; + padding-top: 40px; +} + +div.banner { + position: fixed; + top: 10px; + left: 20px; + margin: 0; + z-index: 1000; + width: 1050px; + text-align: center; +} + +p.banner { + border-radius: 4px; + color: #004831; + background: #76b900; +} \ No newline at end of file diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 0000000..76917f6 --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,9 @@ +{% extends "!layout.html" %} +{% block extrabody %} + +{% endblock %} diff --git a/docs/source/conf.py b/docs/source/conf.py index 2419942..b493f5f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -13,12 +13,11 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -import sphinx_glpi_theme +import os +import sys # sys.path.insert(0, os.path.abspath('.')) -# sys.path.insert(0, os.path.abspath('../..')) +sys.path.insert(0, os.path.abspath('../..')) # -- Project information ----------------------------------------------------- @@ -66,13 +65,19 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'glpi' -html_theme_path = sphinx_glpi_theme.get_html_themes_path() +html_theme = 'sphinx_rtd_theme' +html_theme_options = { + "titles_only": True, + "analytics_id": "G-NVJ1Y1YJHK", +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] +html_css_files = ['css/custom.css'] + +html_baseurl = "https://nvidia-merlin.github.io/distributed-embeddings" # other settings master_doc = 'index'