Add documentation

[badoo]

Add documentation

[arkivanov]

Thanks, now it's more clear. I would like to host docs in the Decompose repository. I could enable GitHub pages for this repository in the settings. Then you could make a PR here with initial setup. Does it sound correct?

[arkivanov]

@plusmobileapps Here is an issue #50 , that would be nice to add to the documentation. I will be happy if you could help with this.

[plusmobileapps]

I see what you are talking about, let me play around with it this weekend and I'll see what I can do about that

[plusmobileapps]

@arkivanov havent looked at the readme recently and missed that new example. I can add that to the documentation as well.

On the topic of the readme duplicating the docs, I have some ideas to slim that down and will try to get a proposal ready over the weekend when adding the other example.

[arkivanov]

@plusmobileapps Big thanks for your work on documentation, this was very helpful! I think this issue can now be closed.

[plusmobileapps]

Hello @arkivanov! I have just started using Decompose in my KMP project and would like to help create the documentation to better understand the whole framework. I have setup Material MkDocs before for personal use on another project and wondering if that is a suitable tool for documenting Decompose. Let me know how I can help assist and get the documentation started 😄

[arkivanov]

Hi @plusmobileapps , that's sounds good! I also wanted to use GitHub.io, and I like the Material design you are proposing. So I see no reason why we should not use it. So let's start with some initial setup from your side? Then I could add some structure with empty pages. And then we could fill it.

[plusmobileapps]

Alright, so I did some initial setup in this repository and the site is published on GitHub.io at https://plusmobileapps.com/decompose-docs/.

I added just a few tabs porting some of the readme over into the sections. If you wanted to start adding some structure to the documentation and then I can help try to fill out some if its anything I might understand (still pretty new to decompose but would like to learn 😄). The MkDocs Material getting started should help get a developer environment set up.

Then I'm not sure if this repo should be forked under your GitHub account since github.io automatically gets redirected to my custom domain. We would just need to change a couple of things in the mkdocs.yml file on that repo to point to the new site.

In the meantime I'm going to figure out how to automate the generation with GitHub Actions anytime the main branch is updated.

[arkivanov]

I thought we can use GitHub pages for this. Like I have this for MVIKotlin: https://arkivanov.github.io/MVIKotlin/

Can we apply material theme there, or is it a different thing?

[arkivanov]

MkDocs looks more complex, like you need to install something etc.
Also why do you think we need some automation? Generating reference docs from KDocs?

[plusmobileapps]

Yes, GitHub Pages is being used to host the website. Sorry if there is confusion because I use GitHub Pages for my personal plusmobileapps.github.io with a custom domain, it seems to also use my custom domain for hosting other projects. So if you actually go to http://plusmobileapps.github.io/decompose-docs/, it just redirects to the custom domain which is why I was wondering if it made sense to have you fork the documentation repository so the domain would be https://arkivanov.github.io/decompose-docs. But it sounds like you were wanting to have the documentation live inside of the decompose GitHub under the docs folder so that it could have the domain: https://arkivanov.github.io/Decompose?

The automation was just when someone merges something into the main branch, it could pull the dependencies needed to generate the site and deploy to the gh-pages branch as opposed to having someone manually run this script themselves. Found out the repo already had a script to do this when the main branch has a commit pushed so no further action would be needed.

[plusmobileapps]

Alright @arkivanov, I created a pull request that sets up Material MkDocs in the repository and the site should be https://arkivanov.github.io/Decompose after it is merged.~~

I got it working in my fork by testing going to https://plusmobileapps.github.io/Decompose/ after the changes were merged into my fork's master branch. Keep in mind from my note prior, if you test that link it will redirect to my custom domain but that should not happen when merged into the main repository.

In reference to one of your points earlier:

MkDocs looks more complex, like you need to install something etc.

If you want to build locally and see what it looks, you would need to download the docker image or install the python dependencies in order to run it. I didn't think that it was too complicated after going through the getting started page, but open to other suggestions as Material MkDocs was just something I have used in the past for documentation

Update

I created a new pull request that cleaned up everything to get the bare minimum added to the repository.

I also wrote some instructions for running the server locally with docker that seemed simple to do with a couple commands.

[arkivanov]

Thanks, I will check!

[arkivanov]

@plusmobileapps Thanks for #34. So it is merged, but there is no gh-pages branch to select in the settings. Should I create it?

[plusmobileapps]

@arkivanov awesome that got merged! It takes a couple minutes once merged for the GitHub Action script to fully run and deploy to the gh-pages branch. I see the branch got generated now here, so you should just need to go into the settings of the repository like in this comment to enable the GitHub Pages site.

[plusmobileapps]

BTW, if you are ever wanting to see the status of the workflows that deploy the documentation then you can look under the actions tab of the repository at this job

[arkivanov]

Thanks! I set it. Did not know that we need to wait for the job before the branch is created.

[plusmobileapps]

No worries, it is that job which will push the deployment to that branch. Well I see it is working now if you go to https://arkivanov.github.io/Decompose/ ! What else can I do to help with the documentation?

[arkivanov]

Thanks again! Now I need to get my head around of what should be the structure and content of the documentaion. I will get back if I need more help.

[plusmobileapps]

I will take a look at that @arkivanov and see what I can come up with. Might have a couple questions for that issue to make sure I can document it correctly.

On a side note, since the GitHub Pages site is now up, should we update the GitHub repository to reflect the documentation website in the top right corner so it is easily accessible? Would obviously replace that link with the https://arkivanov.github.io/Decompose/

[arkivanov]

should we update the GitHub repository to reflect the documentation website

Updated, thanks for pointing on that!

[arkivanov]

@plusmobileapps when we open Https://arkivanov.github.io/decompose and tap on the menu drawer button, the Overview section is already selected. So you need to tap Back to see the main menu. It is quite confusing. Can make the main menu initial?

[arkivanov]

@plusmobileapps thanks for you contribution! World be good if you add the new sample to the documentation (Sample Greetings App), please see the readme.

[arkivanov]

Also the readme is just duplicate of the documentation, would be good to somehow reduce its size by keeping only important information. If you have some ideas and want to contribute, feel free to submit a PR!