Connecting C++ and Python sphinx (#311)

* Remove doc for moving into python
* Include python.rst in toc
* Use 18.04 cp3.7 wheel
* Integrating python documentation

.github/workflows/python.yml

@@ -3,6 +3,7 @@ name: "Python Bindings"
   push:
     branches:
       - main
+      - ci-sandbox
     tags:
       - "v*.*.*"
   pull_request:
@@ -279,3 +280,88 @@ jobs:
       - name: "Static typing checks: pytype"
         run: |-
             python3 -m pytype bindings/python
+
+    docs:
+      runs-on: ubuntu-18.04
+      needs: [python-ubuntu]
+      steps:
+        - name: Checkout
+          uses: actions/checkout@v2
+          with:
+            submodules: recursive
+
+        # Runs javascript to extract push events from both tags and branch (only main, due to workflow trigger)
+        # converts refs/<>/<name> -> <name>
+        # eg:
+        #     refs/head/main   -> main
+        #     refs/tags/v0.1.0 -> v0.1.0
+        #
+        - name: Download artifacts
+          uses: actions/download-artifact@v2
+        - name: Extract tag name
+          id: tag
+          uses: actions/[email protected]
+          if: ${{ github.event_name == 'push' }}
+          with:
+            github-token: ${{ secrets.GITHUB_TOKEN }}
+            script: |
+              const args = context.payload.ref.split("/");
+              [refs, category, ...rest] = args;
+              return rest.join("/");
+
+        # Patches the BERGAMOT_VERSION file used by sphinx-docs at run time to
+        # obtain names like 'main' or 'ci-sandbox' to not confuse with version
+        # based documentation built separately.
+        - name: Deploy-time patch version 
+          run: | 
+              echo ${{steps.tag.outputs.result }} > BERGAMOT_VERSION
+
+        - name: Set up Doxygen
+          run: sudo apt-get install -y doxygen
+
+        - name: Set up Python
+          uses: actions/setup-python@v2
+          with:
+            python-version: 3.7
+
+        - name: Set up dependency cache
+          uses: actions/cache@v2
+          with:
+            path: ~/.cache/pip
+            key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
+            restore-keys: |
+              ${{ runner.os }}-pip-
+
+        - name: Install dependencies
+          working-directory: ./doc
+          run: |
+            python3 -m pip install -r requirements.txt
+            python3 -m pip install ${{github.workspace}}/artifact/bergamot-*-cp37*.whl
+
+        - name: Build documentation
+          working-directory: ./doc
+          run: sphinx-build -b html ./ build/
+
+
+        - name: Deploy 🚀
+          uses: JamesIves/[email protected]
+          if: ${{ github.event_name == 'push' && github.repository == 'browsermt/bergamot-translator' }}
+          with:
+            repository-name: 'browsermt/docs' 
+            branch: gh-pages # The branch the action should deploy to.
+            folder: './doc/build/' # The folder the action should deploy.
+            target-folder: '${{ steps.tag.outputs.result }}' 
+            ssh-key: ${{ secrets.BERGAMOT_SSH_PRIVATE_KEY }}
+
+        # This artifact contains the HTML output of Sphinx only.
+        # With index.html at the root of the produced zip file.
+        # For use for maintainers to download the zip and check render of
+        # documentation while generated at pull-request. 
+        - name: Upload documentation
+          uses: actions/upload-artifact@v2
+          if: ${{ github.event_name == 'pull_request'}}
+          with:
+            name: api-docs
+            path: ./doc/build/
+            if-no-files-found: error
+

doc/conf.py

@@ -14,21 +14,23 @@
 import datetime
 import sys
 
-sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath("."))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'Bergamot Translator'
-copyright = '2021, Bergamot Translator Team'
-author = 'Bergamot Translator Team'
+project = "Bergamot Translator"
+copyright = "2021, Bergamot Translator Team"
+author = "Bergamot Translator Team"
 
 # The full version, including alpha/beta/rc tags
 # TODO: add GitHub commit hash to the version
-version_file = os.path.join(os.path.dirname(os.path.dirname(__file__)), 'BERGAMOT_VERSION')
+version_file = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)), "BERGAMOT_VERSION"
+)
 with open(os.path.abspath(version_file)) as f:
     version = f.read().strip()
-release = version + ' ' + str(datetime.date.today())
+release = version + " " + str(datetime.date.today())
 
 
 # -- General configuration ---------------------------------------------------
@@ -37,24 +39,26 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.mathjax',
-    'sphinx.ext.todo',
-    'breathe',
-    'exhale',
-    'recommonmark',
+    "sphinx.ext.mathjax",
+    "sphinx.ext.todo",
+    "breathe",
+    "exhale",
+    "recommonmark",
+    "sphinx.ext.autodoc",
+    "sphinxarg.ext",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
-    'build',
-    'doxygen',
-    'venv',
-    'README.md',
+    "build",
+    "doxygen",
+    "venv",
+    "README.md",
 ]
 
 
@@ -63,23 +67,23 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
-htmlhelp_basename = 'bergamot-translator'
+html_theme = "sphinx_rtd_theme"
+htmlhelp_basename = "bergamot-translator"
 
 # 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_static_path = ["_static"]
+html_css_files = ["css/custom.css"]
 
 # The base URL which points to the root of the HTML documentation
-html_baseurl = 'http://jerinphilip.github.io/bergamot-translator'
+html_baseurl = "http://jerinphilip.github.io/bergamot-translator"
 
 
 # -- Extension configuration -------------------------------------------------
 
-breathe_projects = { 'bergamot-translator': './doxygen/xml' }
-breathe_default_project = 'bergamot-translator'
+breathe_projects = {"bergamot-translator": "./doxygen/xml"}
+breathe_default_project = "bergamot-translator"
 
 doxygen_config = """
 INPUT                = ../src ../app
@@ -94,27 +98,28 @@
 """
 
 exhale_args = {
-    'containmentFolder'     : './api',
-    'rootFileName'          : 'library_index.rst',
-    'rootFileTitle'         : 'Library API',
-    'doxygenStripFromPath'  : '..',
-    'createTreeView'        : True,
-    'exhaleExecutesDoxygen' : True,
-    'exhaleDoxygenStdin'    : doxygen_config.strip(),
+    "containmentFolder": "./api",
+    "rootFileName": "library_index.rst",
+    "rootFileTitle": "Library API",
+    "doxygenStripFromPath": "..",
+    "createTreeView": True,
+    "exhaleExecutesDoxygen": True,
+    "exhaleDoxygenStdin": doxygen_config.strip(),
 }
 
-primary_domain = 'cpp'
-highlight_language = 'cpp'
+primary_domain = "cpp"
+highlight_language = "cpp"
 
 # A trick to include markdown files from outside the source directory using
 # 'mdinclude'. Warning: all other markdown files not included via 'mdinclude'
 # will be rendered using recommonmark as recommended by Sphinx
 from m2r import MdInclude
 
+
 def setup(app):
     # from m2r to make `mdinclude` work
-    app.add_config_value('no_underscore_emphasis', False, 'env')
-    app.add_config_value('m2r_parse_relative_links', False, 'env')
-    app.add_config_value('m2r_anonymous_references', False, 'env')
-    app.add_config_value('m2r_disable_inline_math', False, 'env')
-    app.add_directive('mdinclude', MdInclude)
+    app.add_config_value("no_underscore_emphasis", False, "env")
+    app.add_config_value("m2r_parse_relative_links", False, "env")
+    app.add_config_value("m2r_anonymous_references", False, "env")
+    app.add_config_value("m2r_disable_inline_math", False, "env")
+    app.add_directive("mdinclude", MdInclude)

doc/index.rst

@@ -17,6 +17,7 @@ This is developer documentation.
    marian-integration
    wasm-example
    api/library_index
+   python
 
 
 

doc/python.rst

@@ -3,8 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-bergamot-translator
-====================================
+Python
+=======
 
 .. toctree::
    :maxdepth: 3

doc/requirements.txt

@@ -5,3 +5,4 @@ sphinx_rtd_theme
 mistune<2.0.0
 recommonmark
 m2r
+sphinx-argparse