dialohq / ocaml-grpc

gRPC library for OCaml
https://dialohq.github.io/ocaml-grpc
BSD 3-Clause "New" or "Revised" License
62 stars 9 forks source link

Add doc generation infra #2

Open wokalski opened 2 years ago

wokalski commented 2 years ago

We don't have ~good~ docs. There's a Makefile with a doc generation script which is a good start. To automatically deploy them to https://dialohq.github.io/ocaml-grpc/ we need to run the doc generation script (preferably in a GitHub action) and then put the result from _build/default/_doc/_html to /docs on the main branch and commit them using the GitHub action user.

It should be as simple as a GitHub workflow like this:

name: Publish docs
on:
  push:
    branches:
      - main 
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Generate docs 
        run: |
          # Run opam install(s)
          make docs
      - name: Commit report
        run: |
          # run only if anything has changed!
          # if $(git diff --quiet) returns a non zero result
          git add docs
          git commit -m "Update docs"
          git push

I wouldn't advise contributors to run the doc generation scripts during development and committing changes because it might introduce some additional conflicts for the generated code that we really don't care about.


To make the docs nicer we should add a .mld index page