Begin autogenerating docs with mkdocs

AlvinKuruvilla commented 2 years ago

This PR starts work on #21 by autogenerating docs with mkdocs and creating a basic Github CI action.

haani-niyaz commented 2 years ago

@AlvinKuruvilla, are these the instructions you followed? https://squidfunk.github.io/mkdocs-material/publishing-your-site/?h=#with-github-actions

The PR spec seems to run the serve command which runs the live preview server, I don't believe it persists anywhere. The instructions indicate that it needs to be published to gh-pages; run: mkdocs gh-deploy --force instead.

I also don't believe we need to nest the docs directory. Any reason for that?

My recommendation would also be to put the index.md mkdocs content within a docs/ci/mkdocs.md file as any CI related stuff should go into docs/ci. The index.md should be reserved for the repo owners (post forking) to add their project content. A simple heading will suffice for now.

AlvinKuruvilla commented 2 years ago

@AlvinKuruvilla, are these the instructions you followed? https://squidfunk.github.io/mkdocs-material/publishing-your-site/?h=#with-github-actions

The PR spec seems to run the serve command which runs the live preview server, I don't believe it persists anywhere. The instructions indicate that it needs to be published to gh-pages; run: mkdocs gh-deploy --force instead.

I also don't believe we need to nest the docs directory. Any reason for that?

My recommendation would also be to put the index.md mkdocs content within a docs/ci/mkdocs.md file as any CI related stuff should go into docs/ci. The index.md should be reserved for the repo owners (post forking) to add their project content. A simple heading will suffice for now.

Hi @haani-niyaz, thank you for the quick reply. The link you provided was the one I followed. I initially had the ci force deploy to gh as well, but I saw it kept failing so I tried just using serve. Regarding your second point about the docs directory nesting, I pushed a new commit that fixes this. In terms of organizing the docs properly, I was planning on looking into that next, I just wanted to get this in as-is first to nail down the core of the setup

haani-niyaz commented 2 years ago