Append FBGEMM CPU documentation (#2244)

Summary:
- Append FBGEMM CPU documentation to the generated Sphinx docs

- Re-organize the documentation in the front page

Pull Request resolved: #2244

Reviewed By: spcyppt

Differential Revision: D52528266

Pulled By: q10

fbshipit-source-id: 36ab286795a01d3ce1a83dc7ca5d674069e81132

CONTRIBUTING.md

@@ -1,11 +1,12 @@
-# Contributing to FBGEMM / FBGEMM_GPU
+# Contributing to FBGEMM and FBGEMM_GPU
 
 We want to make contributing to this project as easy and transparent as
 possible.
 
 ## Code of Conduct
 
-The code of conduct is described in [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
+The code of conduct is described in the
+[Code of Conduct](https://github.com/pytorch/FBGEMM/blob/main/CODE_OF_CONDUCT.md).
 
 ## Pull Requests
 

fbgemm_gpu/docs/Doxyfile.in

@@ -949,10 +949,11 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = "../" \
-                         "../include/" \
+INPUT                  = "../include/" \
                          "../codegen/" \
-                         "../src/"
+                         "../src/" \
+                         "../../include/" \
+                         "../../src/"
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -2338,7 +2339,8 @@ SEARCH_INCLUDES        = YES
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
 INCLUDE_PATH           = "../codegen/" \
-                         "../include/fbgemm_gpu"
+                         "../include/fbgemm_gpu/" \
+                         "../../include/fbgemm"
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the

fbgemm_gpu/docs/src/conf.py

@@ -9,21 +9,32 @@
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+#
+# Configuration is based on:
+# https://github.com/pytorch/pytorch/blob/main/docs/cpp/source/conf.py
+
 import os
 import sys
 
 import pytorch_sphinx_theme
 
+
+# -- Project information -----------------------------------------------------
+
+project = "FBGEMM"
+copyright = "2023, FBGEMM Team"
+author = "FBGEMM Team"
+
+# The short X.Y version.
+version = "0.6"
+
+# The full version, including alpha/beta/rc tags
+release = "0.6.0"
+
+
+# -- Path setup --------------------------------------------------------------
+
 for dir_i in os.listdir("../.."):
     if dir_i == "fbgemm_gpu":
         continue
@@ -32,18 +43,56 @@
         sys.path.insert(0, possible_dir)
 
 
-# -- Project information -----------------------------------------------------
-highlight_language = "C++"
+# Setup absolute paths for communicating with breathe / exhale where
+# items are expected / should be trimmed by.
+# This file is {repo_root}/fbgemm_gpu/docs/src/conf.py
+this_file_dir = os.path.abspath(os.path.dirname(__file__))
 
-project = "fbgemm"
-copyright = "2023, FBGEMM Team"
-author = "FBGEMM Team"
+doxygen_xml_dir = os.path.join(
+    os.path.dirname(this_file_dir),  # {repo_root}/fbgemm_gpu/docs
+    "build",  # {repo_root}/fbgemm_gpu/docs/build
+    "xml",  # {repo_root}/fbgemm_gpu/docs/build/xml
+)
+
+repo_root = os.path.dirname(  # {repo_root}
+    os.path.dirname(  # {repo_root}/fbgemm_gpu
+        os.path.dirname(  # {repo_root}/fbgemm_gpu/docs
+            this_file_dir  # {repo_root}/fbgemm_gpu/docs/src
+        )
+    )
+)
 
-# The full version, including alpha/beta/rc tags
-release = "0.1.2"
 
 # -- General configuration ---------------------------------------------------
 
+# Tell sphinx what the primary language being documented is.
+primary_domain = "cpp"
+
+# Tell sphinx what the pygments highlight language should be.
+highlight_language = "cpp"
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ".rst"
+
+# The master toctree document.
+master_doc = "index"
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+# If true, Sphinx will warn about all references where the target cannot be
+# found.
+nitpicky = True
+
+# Make sure the target is unique
+autosectionlabel_prefix_document = True
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -58,6 +107,12 @@
     "sphinx.ext.napoleon",
 ]
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "pytorch": ("https://pytorch.org/docs/main", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -66,54 +121,97 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
-    "pytorch": ("https://pytorch.org/docs/master", None),
-    "numpy": ("https://numpy.org/doc/stable", None),
-}
 
-# Setup absolute paths for communicating with breathe / exhale where
-# items are expected / should be trimmed by.
+# -- Breathe configuration ---------------------------------------------------
 
 # This should be a dictionary in which the keys are project names and the values
 # are paths to the folder containing the doxygen output for that project.
 breathe_projects = {
-    "fbgemm_gpu": "../build/xml/",
-    "codegen": "../build/xml/codegen/",
+    "FBGEMM": doxygen_xml_dir,
+    "codegen": f"{doxygen_xml_dir}/codegen",
 }
 
 # This should match one of the keys in the breathe_projects dictionary and
 # indicates which project should be used when the project is not specified on
 # the directive.
-breathe_default_project = "fbgemm_gpu"
+breathe_default_project = "FBGEMM"
 
-# If true, Sphinx will warn about all references where the target cannot be
-# found.
-nitpicky = True
-
-# Make sure the target is unique
-autosectionlabel_prefix_document = True
-
-# Tell sphinx what the primary language being documented is.
-primary_domain = "cpp"
-
-# Tell sphinx what the pygments highlight language should be.
-highlight_language = "cpp"
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
 html_theme = "pytorch_sphinx_theme"
 html_theme_path = [pytorch_sphinx_theme.get_html_theme_path()]
+
+# 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".
+# NOTE: sharing python docs resources
+html_static_path = ["_static"]
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
 html_theme_options = {
     "pytorch_project": "fbgemm",
     "collapse_navigation": True,
+    "display_version": True,
     "analytics_id": "UA-117752657-2",
 }
 
-# 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"]
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (
+        master_doc,
+        "fbgemm.tex",
+        "FBGEMM Documentation",
+        "FBGEMM Team",
+        "manual",
+    ),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [(master_doc, "FBGEMM", "FBGEMM Documentation", [author], 1)]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (
+        master_doc,
+        "FBGEMM",
+        "FBGEMM Documentation",
+        author,
+        "FBGEMM",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
+]

fbgemm_gpu/docs/src/fbgemm-cpp-api/QuantUtils.rst

@@ -0,0 +1,20 @@
+Quantization Utilities
+======================
+
+Reference Implementation Methods
+--------------------------------
+
+.. doxygengroup:: fbgemm-quant-utils-generic
+   :content-only:
+
+AVX-2 Implementation Methods
+----------------------------
+
+.. doxygengroup:: fbgemm-quant-utils-avx2
+   :content-only:
+
+AVX-512 Implementation Methods
+------------------------------
+
+.. doxygengroup:: fbgemm-quant-utils-avx512
+   :content-only: