Deploy documentation to public URL

[adamkudrna]

Currently the docs isn't accessible anywhere. Everyone should be able to view it when needed.

Serve the docs as a website to encourage designers use the UI library and to make it accessible to public.

(Taken from #15)

We want to stick to GitHub Pages unless something really serious makes us not to.

The question is, where shall we store the built website and how do we get it there?

Prerequisites

1. GH Pages require a ready-to-deploy, static HTML website when not using Jekyll.
2. We must choose from three possible places to store the generated website.

Options

Storing the website

There are two relevant types of GH Pages:

• project
• organisation
• (user — not relevant for our use case)

We can store the generated site in:

• the original project repository
  • 👍in the same repository
  • 👎cluttering the main source code with generated code or involving awkward checkouts to the detached gh-pages branch, see below
• a separate repository dedicated to generated docs
  • 👍the original repository stays clean from generated code
  • 👎disconnected from the original repository

For project pages, the site is required to reside in either of these:

• gh-pages branch (project pages)
  • 👍not cluttering the main source code with generated code
  • 👎awkward to checkout locally
• master branch, docs directory (project pages)
  • 👍no explosive checkouts involved
  • 👎cluttering the main source code with generated code

For organisation pages or docs-dedicated project pages the site can live in the master branch.

Domain

• github.io:
  • project (the generated site is in the same repository in gh-pages or master branches): https://react-ui-org.github.io/react-ui
  • separate project (the site is generated to a different repository): https://react-ui-org.github.io/react-ui-docs
  • organisation (the generated site is in a separate repository): https://react-ui-org.github.io
• custom domain — sexy, but requires someone to pay the domain

Deployment

• let maintainers do it manually via push to one of destinations above — no guarantee that the docs matches the latest release
• automate the process using third-party GitHub apps/actions or a custom shell script like this one (relates to Document releasing and automate where possible #71)

[bedrich-schindler]

I will start from the bottom.

Deployment

I would like to automate whole process using Github Actions if necessary. They have very friendly configuration and they are free for open source projects.

Domain

I would not select https://react-ui-org.github.io because we might have multiple docs in the future. Others are fine to me.

Storing the website

This is tough to decide. I saw all variants in other open source libraries. gh-pages branch is quite standard workflow that is used by huge organization.

What about having docs repository that will store builded docs only whereas docs will be built when new tag is published to the main repository:

1. You add some feature to main repository
2. You merge pull request with new feature
3. You create new release new tag
4. Github trigger GH actions that will build docs and push builded docs to docs repository
5. Clearly built docs, bingo!

In case we are not able to detect new tag, we can detect build of master branch. In that case, develop branch have to be created for development.

We can also push this code to gh-pages branch. All i want to say is the way how to do it clearly.

[adamkudrna]

@bedrich-schindler I quite agree with you.

Deployment

We should be able to automate it entirely:

1. A release or new Git tag is detected (possibilities are endless)
2. GitHub workflow runs a script similar to this to:
   • build the docs from master branch
   • push the built docs to gh-pages branch (or another repository)
3. GH Pages automatically deploy the built docs

Domain

Remaining options:

1. https://react-ui-org.github.io/react-ui if we store the built docs in gh-pages branch
2. https://react-ui-org.github.io/react-ui-docs or simply https://react-ui-org.github.io/<WHATEVER NAME WE CHOOSE> if we store the built docs in another repository named <WHATEVER NAME WE CHOOSE>

Storing the website

1. I think the best URL is https://react-ui-org.github.io/react-ui which implies using the gh-branch.
2. https://react-ui-org.github.io/react-ui-docs is also fine. The URL is not so cool but the generated code is stored away from our source which is nice. We also should state somehow that this is for built content only since we probably don't want an URL like https://react-ui-org.github.io/react-ui-docs-built (URI must be the same as the repository name).

[mbohal]

I have no strong feelings about this and everything suggested here is acceptable to me. The free domains all seem equally crappy compared to custom domain which we do not want to pay for now ( react-ui.io costs 5069 CZK) .

Since you are asking however, I would prefer:

• automate everything
• store static HTML (build) in separate repo
• use https://react-ui-org.github.io/react-ui-docs

[adamkudrna]

@mbohal Perfect, I will do it that way: automatic deployment via push to a separate repository named react-ui-docs.

I'm seriously considering buying the domain though. According to what I have found it costs “only” 1690 CZK inc. VAT per year which is acceptable. And it will be definitely more cool if we are serious with the project.

[adamkudrna]

Documentation is now live. Automatic deployment is to be solved in #71.