developer_guides: debugability: shell: add usage documentation #508
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| --- | |
| # Tools that can save round-trips to github and a lot of time: | |
| # | |
| # yamllint -f parsable pull_request.yml | |
| # pip3 install ruamel.yaml.cmd | |
| # yaml merge-expand pull_request.yml exp.yml && | |
| # diff -w -u pull_request.yml exp.yml | |
| # | |
| # github.com also has a powerful web editor that can be used without | |
| # committing. | |
| name: Build and Deploy | |
| # yamllint disable-line rule:truthy | |
| on: | |
| push: | |
| branches: | |
| - master | |
| - publish | |
| pull_request: | |
| branches: [master] | |
| # Allows you to run this workflow manually from the Actions tab | |
| workflow_dispatch: | |
| # As of January 2021, no YAML anchors :-( | |
| env: | |
| ubuntu_base_deps: doxygen make default-jre graphviz cmake ninja-build | |
| jobs: | |
| supported-reqs: | |
| name: 'Supported scripts/requirements.txt' | |
| runs-on: ubuntu-22.04 | |
| steps: | |
| - uses: actions/checkout@v3 | |
| # FIXME: remove this time consuming step once github stops | |
| # providing a broken package index, see | |
| # https://github.com/actions/virtual-environments/issues/1757#issuecomment-777700920 | |
| - name: apt-get update github broken package index | |
| run: sudo apt-get update | |
| - name: apt-get install | |
| run: sudo apt-get -y install $ubuntu_base_deps | |
| - name: PATH += .local/bin | |
| run: echo "$HOME/.local/bin" >> $GITHUB_PATH | |
| - name: 'pip install -r scripts/requirements.txt' | |
| run: pip install -r scripts/requirements.txt | |
| # No YAML anchors; this is copy/paste | |
| - name: configure SOF doc | |
| run: | | |
| git clone https://github.com/thesofproject/sof | |
| cmake -GNinja -S sof/doc -B _build_doxy | |
| # TODO: change the (bad) default value for SOF_DOC_BUILD in | |
| # sof-docs/Makefile and remove this command line override | |
| - name: build | |
| run: | | |
| make html VERBOSE=1 SOF_DOC_BUILD=_build_doxy | |
| du -shc _build*/* | |
| - name: prepare file for deploy | |
| if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' }} | |
| run: ./.github/actions/create-publish-folder.sh | |
| # store the build result to artifact, used for later deploy or | |
| # download for debug | |
| # https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts | |
| - name: upload HTML for deploy | |
| if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' }} | |
| uses: actions/upload-artifact@v3 | |
| with: | |
| name: html | |
| path: _build/html | |
| deploy: | |
| needs: supported-reqs | |
| runs-on: ubuntu-22.04 | |
| if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' }} | |
| steps: | |
| # download the build result from the same workflow | |
| # https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts | |
| - name: download HTML | |
| uses: actions/download-artifact@v3 | |
| with: | |
| name: html | |
| path: html | |
| - name: deploy | |
| uses: peaceiris/actions-gh-pages@v3 | |
| with: | |
| personal_token: ${{ secrets.ACTIONS_DEPLOY_KEY }} | |
| publish_dir: ./html/ | |
| publish_branch: master | |
| external_repository: thesofproject/thesofproject.github.io | |
| lax: | |
| name: "PIP_IGNORE_INSTALLED=0 requirements-lax.txt" | |
| runs-on: ubuntu-22.04 | |
| # Makefile downgrades the Sphinx warnings, they are not errors any more | |
| env: {LAX: 1} | |
| steps: | |
| - uses: actions/checkout@v3 | |
| # FIXME: remove this time consuming step once github stops | |
| # providing a broken package index, see | |
| # https://github.com/actions/virtual-environments/issues/1757#issuecomment-777700920 | |
| - name: apt-get update github broken package index | |
| run: sudo apt-get update | |
| - name: apt-get install base dependencies | |
| run: sudo apt-get -y install $ubuntu_base_deps | |
| - name: apt-get instead of pip | |
| run: sudo apt-get -y install | |
| python3-pip python3-setuptools python3-wheel | |
| python3-sphinx python3-breathe python3-docutils | |
| python3-sphinx-rtd-theme python3-sphinxcontrib.plantuml | |
| - name: PATH += .local/bin | |
| run: echo "$HOME/.local/bin" >> $GITHUB_PATH | |
| # should be a no-op | |
| - name: 'pip install -r scripts/requirements-lax.txt' | |
| run: pip install -r scripts/requirements-lax.txt | |
| - name: config tweaks | |
| run: | | |
| # sphinx-build < 1.7 doesn't support "auto" and we're not sure | |
| # all default modules are "thread-safe" | |
| sed -i -e '/SPHINXBUILD/ s/-j *auto/-j 1/' Makefile | |
| # We don't want plantUML to raise the contribution bar | |
| sed -i -e 's/^\(plantuml_output_format *=\).*/\1 "none"/' conf.py | |
| # No YAML anchors; this is copy/paste | |
| - name: configure SOF doc | |
| run: | | |
| git clone https://github.com/thesofproject/sof | |
| cmake -GNinja -S sof/doc -B _build_doxy | |
| - name: build | |
| run: | | |
| make html VERBOSE=1 SOF_DOC_BUILD=_build_doxy | |
| du -shc _build*/* |