diff --git a/.github/workflows/cicd.yaml b/.github/workflows/cicd.yaml index feb94adb..ce33224d 100644 --- a/.github/workflows/cicd.yaml +++ b/.github/workflows/cicd.yaml @@ -83,6 +83,28 @@ jobs: - name: Build website run: npm run build + # Checks that the API reference docs built with shpinx build + test-api-reference-docs: + runs-on: ubuntu-latest + steps: + - name: get code + uses: actions/checkout@v3 + - name: install python + uses: actions/setup-python@v4 + with: + python-version: ${{ env.PYTHON_VERSION }} + - name: install poetry + uses: snok/install-poetry@v1 + with: + version: ${{ env.POETRY_VERSION }} + + - name: Install dependencies + run: make install-sphinx-deps + + - name: Build API documentation + run: | + make apidocs + # Run integration tests against the API (only on the main branch, though). The comprehensive # version runs a matrix of python versions for better coverage. test-comprehensive: @@ -190,6 +212,7 @@ jobs: if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') needs: - test-comprehensive + - test-api-reference-docs runs-on: ubuntu-latest defaults: run: @@ -205,7 +228,9 @@ jobs: - name: Install dependencies run: npm install - name: Build website - run: npm run build + run: | + cd .. + make docs-comprehensive - name: Deploy website (if on main branch) # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus uses: peaceiris/actions-gh-pages@v3 diff --git a/.github/workflows/sphinx_docs.yaml b/.github/workflows/sphinx_docs.yaml deleted file mode 100644 index 38a5832f..00000000 --- a/.github/workflows/sphinx_docs.yaml +++ /dev/null @@ -1,35 +0,0 @@ -name: Build API Reference docs using sphinx - -on: - push: - branches: - - main - pull_request: - branches: - - main - -env: - POETRY_VERSION: "1.6.1" - PYTHON_VERSION: "3.10" - -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: get code - uses: actions/checkout@v3 - - name: install python - uses: actions/setup-python@v4 - with: - python-version: ${{ env.PYTHON_VERSION }} - - name: install poetry - uses: snok/install-poetry@v1 - with: - version: ${{ env.POETRY_VERSION }} - - - name: Install dependencies - run: make install-sphinx-deps - - - name: Build API documentation - run: | - make apidocs \ No newline at end of file diff --git a/Makefile b/Makefile index b9d3054e..2076490f 100644 --- a/Makefile +++ b/Makefile @@ -72,12 +72,25 @@ sphinx-help: # The .PHONY directive tells make that `apidocs` and `html` are labels for # commands. `apidocs: html` allows us to generate docs by running # `make apidocs` instead. -.PHONY: apidocs html - +.PHONY: docs-comprehensive apidocs html + +# Start an interactive server to test docs locally +develop-docs-comprehensive: docs-comprehensive + cd docs && npm start + +## Builds docs comprehensively (integrating API reference docs built +## with sphinx into the docusaurus docs). +docs-comprehensive: apidocs + rm -rf docs/static/api-reference-docs + rm -rf docs/build/api-reference-docs + mkdir docs/static/api-reference-docs + mv build/html/* docs/static/api-reference-docs/ + + cd docs && npm run build + apidocs: poetry run make html html: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0) - @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/docs/.gitignore b/docs/.gitignore index b2d6de30..e0b97416 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -7,6 +7,7 @@ # Generated files .docusaurus .cache-loader +.package-lock.json # Misc .DS_Store diff --git a/docs/README.md b/docs/README.md index 210a998d..c2036e11 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,9 +9,7 @@ The docs are included with the SDK so that we can automate testing of the code s Doc changes are published automatically when they're merged to main. To preview changes, build and host the site locally. You'll need a reasonably modern version of `npm` and then: ``` -npm install -npm run build # looks for any errors -npm start # starts interactive server +make develop-docs-comprehensive ``` and then open [http://localhost:3000/python-sdk](http://localhost:3000/python-sdk). diff --git a/docs/docs/api-reference/_category_.json b/docs/docs/api-reference/_category_.json new file mode 100644 index 00000000..f9a04b2b --- /dev/null +++ b/docs/docs/api-reference/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "API Reference", + "position": 5, + "collapsed": false +} \ No newline at end of file diff --git a/docs/docs/api-reference/api-reference.md b/docs/docs/api-reference/api-reference.md new file mode 100644 index 00000000..8ccd363a --- /dev/null +++ b/docs/docs/api-reference/api-reference.md @@ -0,0 +1,3 @@ +# API Reference + +Click [here](pathname:///python-sdk/api-reference-docs/) to access a detailed documentation of the SDK with all available methods. \ No newline at end of file diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index c8cefe51..95166cab 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -25,7 +25,7 @@ const config = { trailingSlash: false, onBrokenLinks: "throw", - onBrokenMarkdownLinks: "warn", + onBrokenMarkdownLinks: "throw", // Even if you don't use internalization, you can use this field to set useful // metadata like html lang. For example, if your site is Chinese, you may want @@ -98,6 +98,11 @@ const config = { label: "Applications", position: "left", }, + { + href: "pathname:///python-sdk/api-reference-docs/", + label: 'API Reference', + position: "left", + }, { href: "https://github.com/groundlight/python-sdk", label: "GitHub", diff --git a/sphinx_docs/conf.py b/sphinx_docs/conf.py index d7aa69ee..e05c8d8b 100644 --- a/sphinx_docs/conf.py +++ b/sphinx_docs/conf.py @@ -45,4 +45,4 @@ def get_version_name() -> str: # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "sphinx_rtd_theme" -html_static_path = ["_static"] +html_static_path = ["_static"] \ No newline at end of file