[doc] add python sphinx python api (wenet-e2e#1736)

* [doc] add python sphinx python api * fix requirements * remove torch dependency * use old pip install * use original sphinx * fix toc * add torch * refine doc workflows * fix
Mddct · Mar 12, 2023 · ac41775 · ac41775
1 parent 76adcfe
commit ac41775
Show file tree

Hide file tree

Showing 4 changed files with 53 additions and 24 deletions.
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
@@ -3,39 +3,53 @@ on:
   workflow_dispatch:
   pull_request:
     paths:
-      - '**.md'
+      - 'docs/**'
+      - 'wenet/**.py'
   push:
     branches:
       - main
     paths:
-      - '**.md'
+      - 'docs/**'
+      - 'wenet/**.py'
 
 jobs:
   docs:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        torch: ["1.13.1"]
+        python-version: ["3.8"]
     steps:
-    - uses: actions/checkout@v1
+      - uses: actions/checkout@v1
 
-    # install sphinx related package and build sphinx files
-    - uses: ammaraskar/sphinx-action@master
-      with:
-        docs-folder: "docs/"
-        pre-build-command: "pip install sphinx-markdown-tables nbsphinx jinja2 recommonmark sphinx_rtd_theme"
+      - name: Setup Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
 
+      - name: Build doc
+        shell: bash
+        run: |
+          cd docs
+          python3 -m pip install -r ./requirements.txt
+          make api
+          make html
 
-    # add .nojekyll to notice Pages use the _* dirs
-    - name: copy the generated site
-      if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-      run: |
-        mkdir public
-        touch public/.nojekyll
-        cp -r docs/_build/html/* public/
+      # add .nojekyll to notice Pages use the _* dirs
+      - name: copy the generated site
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        run: |
+          mkdir public
+          touch public/.nojekyll
+          cp -r docs/_build/html/* public/
 
-    # push to gh-pages branch
-    - name: github pages deploy
-      if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-      uses: peaceiris/actions-gh-pages@v2.3.1
-      env:
-        PERSONAL_TOKEN: ${{ secrets.GITHUB_TOKEN  }}
-        PUBLISH_BRANCH: gh-pages
-        PUBLISH_DIR: public
+      # push to gh-pages branch
+      - name: github pages deploy
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        uses: peaceiris/actions-gh-pages@v2.3.1
+        env:
+          PERSONAL_TOKEN: ${{ secrets.GITHUB_TOKEN  }}
+          PUBLISH_BRANCH: gh-pages
+          PUBLISH_DIR: public
diff --git a/docs/Makefile b/docs/Makefile
@@ -5,7 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SPHINXPROJ    = Wenet
+SPHINXPROJ    = wenet
 SOURCEDIR     = .
 BUILDDIR      = _build
 
@@ -15,6 +15,11 @@ help:
 
 .PHONY: help Makefile
 
+api:
+	sphinx-apidoc -f --separate --module-first -d 2 -o ./python_api ../wenet
+	sed -i 's:^wenet:Python API Reference:g' ./python_api/modules.rst
+	sed -i 's:^=====:====================:g' ./python_api/modules.rst
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

diff --git a/docs/reference.rst b/docs/reference.rst
@@ -7,4 +7,5 @@ Reference
 
    ./python_binding.md
    ./papers.md
+   ./python_api/modules.rst
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,9 @@
+jinja2
+nbsphinx
+sphinx
+recommonmark
+sphinx-markdown-tables
+sphinx-rtd-theme
+torch
+torchaudio
+typeguard
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,4 +7,5 @@ Reference

		./python_binding.md
		./papers.md
		./python_api/modules.rst