Begin autogenerating docs with mkdocs

[AlvinKuruvilla]

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

[haani-niyaz]

@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]

@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]

I initially had the ci force deploy to gh as well, but I saw it kept failing so I tried just using serve

Hi @AlvinKuruvilla, can you elaborate on what the failure was?

[haani-niyaz]

See #21 (comment)

[haani-niyaz]

Closing. See #30.

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information