docs: Add basic SEO and semver to calver change

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,

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.
+

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/[email protected]
+sphinxcontrib-copydirs@git+https://github.com/mikemckiernan/[email protected]
+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

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;
+}

docs/source/_templates/layout.html

@@ -0,0 +1,9 @@
+{% extends "!layout.html" %}
+{% block extrabody %}
+  <div class="banner">
+    <p class="banner">
+      Beginning in January 2023, versions for all NVIDIA Merlin projects
+      will change from semantic versioning like <code>4.0</code>
+      to calendar versioning like <code>23.01</code>.</p>
+  </div>
+{% endblock %}

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'