Added documentation website by sphinx

JinIgarashi commented 2 years ago

@hfu @ubukawa @miya0001 @naogify

Description

I tried to introduce website for documentation of charites by sphinx under docs folder.

Currently, I just transferred information from README.md only. We may add more information in the website. Also, in the future, we can implement i18n with transifex.

Build and deploy to gh-pages branch were successfully done. https://github.com/unvt/charites/tree/gh-pages

Now, it requires Github Pages settings. However, I don't have any permission to change settings.

Could you do settings of gh-pages in Charites? After setting of gh-pages, the following URL should be available for charites.

https://unvt.github.io/charites

Some screenshots is here

Type of Pull Request

[ ] Adding a feature
[ ] Fixing a bug
[x] Maintaining documents
[ ] Others ()

Verify the followings

[x] Code is up-to-date with the main branch
[x] No build errors after npm run build
[x] No lint errors after npm run lint
[x] No errors on using charites help globally
[x] Make sure all the exsiting features working well

Refer to CONTRIBUTING.MD for more details.

JinIgarashi commented 2 years ago

I found gh-pages menu on settings, I did it. Now https://unvt.github.io/charites/ is available. However, there is some problems of appearance...

JinIgarashi commented 2 years ago

@hfu @ubukawa @miya0001 @naogify Now, documentation is available on Github Pages - https://unvt.github.io/charites/. Could you check it? I also deleted duplicated information from README.md

JinIgarashi commented 2 years ago

@hfu @ubukawa @miya0001 @naogify charitesでREADMEでなくきちんとしたドキュメントがあり、今後海外の方も翻訳しやすい環境があった方が良いと思い、トライアルでこのPRを立てさせていただきましたが、特に反応もなく、不要なようですので、クローズさせていただきます。gh-pagesブランチも削除しておきます。

ubukawa commented 2 years ago

@JinIgarashi さん、提案ありがとうございました。こちら、一度見てコメントを共有させていただくのを失念しておりました。失礼しました。

私自身は、このようなツールがあることを知らなかったのですが、Readmeだけで説明が足りなくなってきたときには便利だと思います。ただ、このあと、どのくらいドキュメントを作るかのイメージにもよると思います。どんな文書を作るかお考えがありますか？例えば、私は、英語を話す同僚向けに、先日Qiitaでメモをつくっていましたがこれもマークダウンなので、こちらに移植できるかもしれませんね。　https://qiita.com/T-ubu/items/e6794b81e45dea34548c

あと、最近はmainブランチでGitHubページのホストもできていたように思ったのですが、このツールはgh-pagesブランチを作らないといけないのかもちょっと調べようかと思っていました。このあたり、使い方で便利に使えたというご経験があればおしえてください。

コメントの共有が遅くてすみません。

JinIgarashi commented 2 years ago

@ubukawa mainブランチでGithub pagesにホストするのはそれに必要なHTMLファイルなどすべてmainブランチに入れておかないといけないので、gh-pagesブランチにホストする方がスッキリしていい気がします。このPRで作ったのはmainブランチにマージされるとGithub actionで自動でビルドしてgh-pagesにプッシュするようにしていました。多言語対応はこのPRではしていませんが、世間一般のFOSS4Gソフトウェアの多くがSphinxとTransifexを使って多言語化しているので、その仕組みを流用もできると考えていました。基本的にはGithubリポジトリのドキュメントは全て英語で書いて、ビルドする際にTransifexから翻訳をダウンロードするという感じになると思っています。

コンテンツについてはひとまずREADMEをそのまま展開しただけですが、使い方の説明をするのにケーススタディ的なページを作ったり、サンプルを載せたり、工夫できるところはあると思います。READMEだけでやるよりはビジュアル的にも全然良いと思います。

Sphinxはマークダウンではなく、reStructuredTextという形式ですが比較的描きやすいフォーマットではあると思います。もしこのPRが必要であれば、Restore branchして再オープンしていただいて構いません。

JinIgarashi commented 2 years ago

UNVTの方のgh-pagesで公開するのは微妙なので、自分のOrganizationにフォークしたリポジトリで公開しておきました。 https://watergis.github.io/charites/

ubukawa commented 2 years ago

@JinIgarashi さん、早速ありがとうございます。便利そうですね。ここだけではなくていろいろな場面で使えそうですね。 charitesのレポジトリにすぐつけるかどうかは他の方のコメントも聞きたいですが、私自身はまだ使ったことがないのでどんな仕組みなのか少し試してみたいと思います。

今週は別件で手が回らないかもしれませんが、今月のどこかで試してみたいので、watergisのcharitesをしばらくそのままにしておいていただけないでしょうか。ドキュメントのためにgh-pagesを作るということですね。もしブランチ名を変えてもいいのなら、documentとかしておいてもよさそうですね。

reStructuredTextもちょっと試してみます！いろいろ教えていただきありがとうございます。

ubukawa commented 2 years ago

Dear @hfu @ubukawa @miya0001 @naogify and @JinIgarashi , Now, I have checked the sphinx and I think this branch for documentation is useful. (Now, we have a lot of information on Readme, so it would be useful to have a document for charites).

If you agree, I would like to restore the branch and establish a page with gh-pages branch.

Thank you for your kind attention! I wish you happy holidays!

JinIgarashi commented 2 years ago

@ubukawa Thank you for trying sphinx! I believe it helps us manage documents, particularly in multiple languages in the future. Also, it might be better if we can keep README.md simple. If others agree to manage documentation by sphinx, you can restore branch, then reopen this PR, it will deploy documentation when PR is merged into main. We can start making documentations in English slowly...

JinIgarashi commented 2 years ago

@ubukawa I just reopened PR

ubukawa commented 2 years ago

@JinIgarashi さん、ありがとうございます。この間、他の方から特に異論もないのでPRをマージしたいかなと思っていたのですが、その前に一つ確認させてください。

以前、「gh-pagesブランチにホストする方がスッキリしていい気がします」ということで教えていただいたその通りだなぁとおもったのですが、今回はmainブランチへのマージということでしょうか？ GitHub Pageの設定で add/doc ブランチをホームページのブランチにすることもできますがどうでしょうか？

JinIgarashi commented 2 years ago

@ubukawa ありがとうございます。ソースコードのリポジトリのdocsフォルダ以下には最終的なホームページのhtmlは入っていません。.gitignoreで除外するようにしています。このPRがmainにマージされると、Github ActionsがSphinxのサイトをビルドして、docs/buildフォルダ以下にhtmlを生成してから、gh-pagesに自動デプロイする仕組みです。ドキュメントのhtmlを入れて公開するブランチ名をgh-pages以外にすることも可能ですが、その場合はCIのパラメータの変更が必要です。よろしくお願いします。

JinIgarashi commented 2 years ago

@ubukawa マージするときに、squash and mergeで一つのコミットにまとめていただけると助かります。CI周りのテストとかで無駄なコミットができてるので…、よろしくお願いします。

ubukawa commented 2 years ago

Thank you. I have merged this. gh-pages branch is also released as GitHub page. I wish you a happy new year!

JinIgarashi commented 2 years ago

@ubukawa マージありがとうございます。Transifex連携したPR #84 も作成してます。シークレットキーの登録がまだなので、CIのテストはまだできていませんが毎日UTC0時にTransifexに最新のドキュメントをアップロードし、gh-pagesを更新するような感じのCIにしました。

unvt / charites