Create and publish documentation site to Github Pages?

[marcospereira]

Hey folks,

The documentation right now is somewhat split into two different files:

1. README.md
2. DOCUMENTATION.md

With some duplications between them, documentation being a single file covering different topics, and navigation being directly to GitHub web page. Also, while jte supports both Java and Kotlin, the docs don't cover Kotlin (or offer kte examples).

To be honest, none of these are big problems, which is a statement of how simple and well-designed jte is. But I thought we could improve the docs experience by using a docs-site generator and publishing it to GitHub pages.

[marcospereira]

Okay, here is a try using Material for MkDocs.

https://marcospereira.github.io/jte/

There are many details to fix/improve, but it is a good start. A few nice things there already:

1. Light/dark mode
2. Code tabs
   
3. Note/info/tip/warning boxes:
   
4. Search
   
5. All seamless published by a Github Action: https://github.com/marcospereira/jte/blob/docs/poc-mkdocs/.github/workflows/publish-docs.yml.

@casid @edward3h, WDYT? Is it worth to invest extra time to get it done?

[casid]

@marcospereira that's fantastic!

There currently is a separate Github project to generate the jte website https://github.com/casid/jte-website/, which populates https://jte.gg/

It would be really cool to have the documentation you generated available on jte.gg. I would say we could replace the current landing page entirely with the documentation you've created. This would also spare me from bumping the version on the jte website each time we're doing a new release :-)

If we add your Github Action to the jte repository, I'd think I then would just need to tell Github to publish the jte website from the jte repository and no longer from jte-website.

[casid]

I had a closer look at your repository. Is there a way that we can avoid the duplication of README.md / DOCUMENTATION.md and the markdown in docs?

[marcospereira]

It would be really cool to have the documentation you generated available on jte.gg. I would say we could replace the current landing page entirely with the documentation you've created. This would also spare me from bumping the version on the jte website each time we're doing a new release :-)

Yeah, that sounds like a good plan. :-)

If we add your Github Action to the jte repository, I'd think I then would just need to tell Github to publish the jte website from the jte repository and no longer from jte-website.

I don't know for sure how the process works, but it seems that you need to change the domain configuration for GH Pages from one repo to another.

I had a closer look at your repository. Is there a way that we can avoid the duplication of README.md / DOCUMENTATION.md and the markdown in docs?

I would keep DOCUMENTATION.md file with only a note pointing to the new docs location. Search engines index that file, so having it there as a pointer would be good. I would also keep README.md minimal and point to the docs. I can give it a try later.

[marcospereira]

@casid, I've just created #288. Closing the discussion since we can make decisions there. :-)

[casid]

Thanks, will do!