Add documentation with Material Mkdocs and GitHub Action to build/deploy

[plusmobileapps]

Overview

Add documentation with Material MkDocs to the repository.

Description

• ported the necessary files from Material MkDocs into the repository with a skeleton configuration for Decompose
• added a GitHub action that can automatically build and deploy documentation changes to GitHub Pages. So the website after this should be https://arkivanov.github.io/Decompose

Demo

https://plusmobileapps.github.io/Decompose

Issue

Github Issue

[arkivanov]

Thanks! I have few more questions.
Can we/should we deploy to the main branch?
Why the deployment is a thing here? E.g. I have setup docs for MVIKotlin library here. So I just selected main branch, a folder and a theme, and that's it. All MD files are in the docs folder. There is index.md, which is the main page. The site is updated automatically when I change docs files. No workflows required.

[plusmobileapps]

So after looking between the two types of documentation, the MVIKotlin library uses one of the preconfigured GH pages themes that will automatically build a Jekyll site and deploy changes from the main branch.

Material Mkdocs being a custom theme for GitHub Pages, will have a similar setup having the main branch with a docs/ folder and mkdocs.yml file. Then in order to translate Material Mkdocs into a Jekyll site for GitHub Pages, is where the deployment script comes in which will run the mkdocs gh-deploy --force command pushing the built Jekyll site to the gh-pages branch. So the repository settings would need to be configured to have the GitHub Pages site built from the gh-pages branch.

Just two different ways for building a documentation website on GitHub Pages. I'm fine using one of the themes provided as the setup is simpler only needing to edit the markdown files for preview. I just like the feature set and UI Material Mkdocs brings to documentation, that I think its worth the extra setup of seeing the changes locally in the browser before deploying with docker and the GitHub Action script to automatically deploy the changes to your GitHub Pages site.

[arkivanov]

Thanks for the explanation! Let's try MkDocs and see how it goes. Should I first configure the repository? If so, should I do it before merging this branch?

[plusmobileapps]

I believe you will need to merge the branch first so that the GitHub Action will build and deploy to the gh-pages branch. Then you should be able to go to the repository settings and select that branch as the publishing source for GitHub Pages. This is how I configured the repository on my fork to get the documentation up and running.