aerogear / offix

GraphQL Offline Client and Server
https://offix.dev
Apache License 2.0
758 stars 45 forks source link

Use docusaurus for the docs #72

Closed wtrocki closed 5 years ago

wtrocki commented 5 years ago

Feature Request

Use docusaurus for the documentation as suggested in https://github.com/aerogear/offix/pull/68 Target of this issue is to migrate existing docs to docusaurus.

wtrocki commented 5 years ago

Additionally, we should be moving to gh-pages branch to separate between production and development docs.

wtrocki commented 5 years ago

After checking other repositories I think we can maintain 2 versions of the current docs and have them both in docs folder.

offix.dev will point to release folder3 offix.dev/preview will point to the preview master folder.

This means that we will need to have duplication of the docs but benefits are that we do not edit released one until we do some hotfix.

StephenCoady commented 5 years ago

@wtrocki this sounds good to me. Will the duplication you mention just be an overwrite of what is already there with the /preview version? If thats the case then this sounds like a good solution to me. We could possibly even make that part of our release pipeline.

wtrocki commented 5 years ago

I mean:

/docs/preview
/docs/latest
index.html pointing to /latest

At the time of the release preview and latest will have identical content. This way we can avoid hassle and always do hotfixes without pushing unreleased features. Great idea to have it as a relase pipeline.

darahayes commented 5 years ago

I love this idea. It's simple and it works really well. I've seen a couple of projects do it this way and I've always been happy to use their docs. BTW, docusaurus has some capabilities to automatically generate a version of the docs. For example, it is possible to run some command/script that will result in offix.dev/0.5.0.

You can basically cut a release of the docs from the current version and then that release stays there as its own set of files that will not change. https://docusaurus.io/docs/en/versioning

wtrocki commented 5 years ago

Yep. That will be it with the notion that it is best to not overload repository and maybe keep 2 last versions out there.

wtrocki commented 5 years ago

Going to apply something like https://graphback.offix.dev

darahayes commented 5 years ago

@wtrocki this is really nice!

LakshanKarunathilake commented 5 years ago

Can I work on this issue @wtrocki

wtrocki commented 5 years ago

Assigned. My recommendation would be to keep things simple. Initialize website etc. See our other project https://graphback.dev

darahayes commented 5 years ago

Hi @LakshanKarunathilake 👋 thanks for showing an interest in our project! If you need advice or have any questions about this issue, feel free to post here and we will do our best to help.

wtrocki commented 5 years ago

update from chat: We going to create 2 PR's - one with just docs migrated. Second with the webpage styling - can be similar as https://graphback.dev

darahayes commented 5 years ago

Done in #199