Generate apidoc on build

[vsaw]

Closes #334

[tdurand]

nice, but can we leave the apidoc in the /apidoc directory, otherwise we can't use the static pages of github to serve it: https://opendatacam.github.io/opendatacam/apidoc/ ?

[vsaw]

Ah I have not thought about this. I believe with github actions there should be a way to render a static page on every commit and serve it without having to have the build artifacts in git :-)

Will need to look into it first though.

Update

Quick googling found me https://github.com/marketplace/actions/github-pages-action for example. So it should be possible. Will update the PR when I get around :-)

But you might need to look and check if the github pages settings are done correctly as I can not see or change any settings for the repository.

[tdurand]

okay ! just let me know what I need to do on the github page config and I'll do it 😎

[vsaw]

@tdurand I've updated the pull request to do the following:

At any push in the master branch the apidoc.yml action will be triggered. The action will build the apidoc from source and then push the build artifacts to the gh-pages branch. GitHub can then serve the API documentation from the gh-pages branch, leaving the master branch (and any other branch) free of any build artifacts.

For this action to work you will need to make the following changes to the repository

1. Set GitHub to serve the documentation from the gh-pages branch. See https://github.com/marketplace/actions/github-pages-action#%EF%B8%8F-first-deployment-with-github_token
2. As this action performs writes on the gh-pages branch, make sure that you only share read tokens with your forks. Check https://github.com/opendatacam/opendatacam/settings/actions

If you want to see this action run successfully visit https://github.com/vsaw/opendatacam/actions/runs/436279892. This run created the API documentation that you can see at https://vsaw.github.io/opendatacam/ (the HTML generated by apidoc can be found at the gh-pages branch)

[tdurand]

great ! only downside I see now (sorry) is that we will not have the nice Markdown as HTML like we had: https://opendatacam.github.io/opendatacam/ for the rest of the documentation.. but I think no one was reading the documentation there anyways.. And I think if we ever want to have a website for documentation it should be something a bit more usable than just the raw Markdown file as HTML.. something with a nice navigation menu 😁

So let's go , will try to merge this and setup correctly the github page !

[vsaw]

great ! only downside I see now (sorry) is that we will not have the nice Markdown as HTML like we had: https://opendatacam.github.io/opendatacam/ for the rest of the documentation..

With a bit more effort this can be implemented. We just need to call Jekyll or any static page generator and include the apidoc as a sub-page. Do you want me to fix this?

[tdurand]

If you don't mind would be nice to have to be able to link to the documentation outside github markdown.

[tdurand]

but let me know if it is not a quick fix and I'll go with this for now

[vsaw]

but let me know if it is not a quick fix and I'll go with this for now

I've run into some undocumented behavior of GitHub. It seems that it does not automatically convert Markdown pages to HTML. So far I've only been able to do this on master and development. But I believe I can get it to do a Markdown to HTML conversion by moving the page to a subfolder. Will try this quickly.

[vsaw]

Got it working now. Apparently you can bypass GitHubs built in Jekyll, which the Action did (unknowingly).

For proof of work see:

• https://vsaw.github.io/opendatacam/
• https://github.com/vsaw/opendatacam/actions/runs/436482323

See also https://github.blog/2009-12-29-bypassing-jekyll-on-github-pages/