GitHub actions hooks for GitHub pages docs website. (#1599)

Summary:
These hooks, along with the creation of the `gh-pages` branch with a Sphinx-powered website ([preview](https://beauby.github.io/faiss/)) will ensure automatic rebuild of the C++ API (doxygen) docs upon modification on `master`.
Moreover,  direct changes to the `gh-pages` branch will trigger a rebuild of the website as well.

Pull Request resolved: https://github.com/facebookresearch/faiss/pull/1599

Reviewed By: wickedfoo

Differential Revision: D25723322

Pulled By: beauby

fbshipit-source-id: fafeed64b393dce8c569f9fd1f5bc3b004706589

.github/workflows/publish-docs.yml

@@ -0,0 +1,44 @@
+name: publish-docs
+on:
+  page_build:
+    branches:
+      - gh-pages
+    paths-ignore:
+      - 'docs/**'
+  workflow_run:
+    workflows: [update-doxygen]
+    types:
+      - completed
+jobs:
+  build_and_publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      - name: Checkout gh-pages
+        run: |
+          git fetch origin gh-pages
+          git checkout gh-pages
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+      - name: Generate html
+        run: |
+          make html
+          git rm -rf docs
+          mv _build/html docs
+          touch docs/.nojekyll
+      - name: Push changes
+        run: |
+          git config --global user.email "[email protected]"
+          git config --global user.name "$GITHUB_ACTOR"
+          git add docs
+          if [ -n "$(git status --porcelain)" ]
+          then
+            git commit docs -m "Sphinx rebuild ($(git rev-parse --short gh-pages))."
+            git push origin gh-pages
+          fi

.github/workflows/update-doxygen.yml

@@ -0,0 +1,40 @@
+name: update-doxygen
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'faiss/**'
+jobs:
+  doxygen:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      - name: Install dependencies
+        run: |
+          sudo apt-get install -y doxygen
+          python -m pip install --upgrade pip
+          pip install breathe
+      - name: Generate doxygen xml
+        run: doxygen
+      - name: Push changes
+        run: |
+          git config --global user.email "[email protected]"
+          git config --global user.name "$GITHUB_ACTOR"
+          mkdir ./tmp
+          mv xml ./tmp/xml
+          git fetch origin gh-pages
+          git checkout gh-pages
+          git rm -rf xml cpp_api
+          mv ./tmp/xml ./xml
+          breathe-apidoc -o cpp_api xml
+          git add xml cpp_api
+          if [ -n "$(git status --porcelain)" ]
+          then
+            git commit -m "Update API docs ($(git rev-parse --short master))."
+            git push origin gh-pages
+          fi

Doxyfile

@@ -125,7 +125,7 @@ ALWAYS_DETAILED_SEC    = NO
 # operators of the base classes will not be shown.
 # The default value is: NO.
 
-INLINE_INHERITED_MEMB  = NO
+INLINE_INHERITED_MEMB  = YES
 
 # If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path
 # before files name in the file list and in the header files. If set to NO the
@@ -424,7 +424,7 @@ EXTRACT_STATIC         = NO
 # for Java sources.
 # The default value is: YES.
 
-EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_CLASSES  = NO
 
 # This flag is only useful for Objective-C code. When set to YES local methods,
 # which are defined in the implementation section but not in the interface are
@@ -735,7 +735,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../
+INPUT                  = ./faiss
 
 # 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
@@ -755,7 +755,7 @@ INPUT_ENCODING         = UTF-8
 # *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf,
 # *.qsf, *.as and *.js.
 
-FILE_PATTERNS          = *.cpp *.h *.cu *.cuh
+FILE_PATTERNS          = *.h *.cuh
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -770,8 +770,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = ../benchs ../c_api ../demos ../python ../tests \
-                         ../gpu/test ../tutorial ../misc
+EXCLUDE                = gpu/test
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -787,7 +786,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = */impl/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -993,7 +992,7 @@ IGNORE_PREFIX          =
 # If the GENERATE_HTML tag is set to YES doxygen will generate HTML output
 # The default value is: YES.
 
-GENERATE_HTML          = YES
+GENERATE_HTML          = NO
 
 # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1772,7 +1771,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of