Work out best way to generate the API documentation automatically and publish it with netlify.

[SamVanhoutte]

Option 1 : generate md files in CI-build and commit to branch

This was tested and tried, but resulted in endless loops of CI-build. Snippets for ci-build.yaml:

# The persistCredentials will leave the OAuth token in the Git config after the initial fetch
- checkout: self
  persistCredentials: true

- script: echo "Source branch is $(System.PullRequest.SourceBranch)"
- script: echo "Name user is $(Build.RequestedFor)"
- script: echo "Email user is $(Build.RequestedForEmail)"

- script: python -m pip install --upgrade pip setuptools wheel pdoc3 lazydocs
  displayName: 'Install tools'

- script: |
    lazydocs --output-path docs/preview --overview-file="api.md" arcus/ml
    git config user.email "" #Should be retrieved
    git config user.name "" #Should be retrieved
    git add docs/preview
    git commit -m "Add SDK docs from Build $(Build.BuildId) [***NO_CI***]"
    git push origin HEAD:$(System.PullRequest.SourceBranch) --tags
  displayName: 'Generate code documentation'
  continueOnError: false

Option 2 : Generate the documentation in the Netlify action

Option 3 : find a way to automatically force the generation of the docs at client side / build side

This is the current implementation, but requires the dev to consider rebuilding the documentation, before committing. As this is performed by a test, this hopefully means, the test will be executed locally, before pushing to the repo.

[stijnmoreels]

We can maybe include this when we generate a new version of the docs, bc that's usually the moment that we determine that we mark the current available features. Besides the Docusaurus generation, we can include in the package.json a script command that does both (Docusuarus versioning and lazy docs generation). Just an idea.