diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml deleted file mode 100644 index 3874822b8..000000000 --- a/.github/workflows/doc.yml +++ /dev/null @@ -1,89 +0,0 @@ -name: Documentation - -on: - push: - branches: [ main, ci-sandbox ] - tags: ['v[0-9]+.[0-9]+.[0-9]+'] - pull_request: - branches: [ '**' ] - -jobs: - api-documentation: - runs-on: ubuntu-latest - 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/<>/ -> - # eg: - # refs/head/main -> main - # refs/tags/v0.1.0 -> v0.1.0 - # - - name: Extract tag name - id: tag - uses: actions/github-script@0.2.0 - 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 - - - name: Build documentation - working-directory: ./doc - run: sphinx-build -b html ./ build/ - - - - name: Deploy 🚀 - uses: JamesIves/github-pages-deploy-action@4.1.3 - 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 - diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml index 653964a8a..ef18b3ffa 100644 --- a/.github/workflows/python.yml +++ b/.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/<>/ -> + # 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/github-script@0.2.0 + 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/github-pages-deploy-action@4.1.3 + 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 + diff --git a/doc/conf.py b/doc/conf.py index 8a8f4224c..7c4bfd50c 100644 --- a/doc/conf.py +++ b/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) diff --git a/doc/index.rst b/doc/index.rst index 5be3857a3..54dc1e8dc 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -17,6 +17,7 @@ This is developer documentation. marian-integration wasm-example api/library_index + python diff --git a/doc/python.rst b/doc/python.rst index 4c8574dee..0426f349f 100644 --- a/doc/python.rst +++ b/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 diff --git a/doc/requirements.txt b/doc/requirements.txt index 28e6e70ca..d95cc684c 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -5,3 +5,4 @@ sphinx_rtd_theme mistune<2.0.0 recommonmark m2r +sphinx-argparse