Use MkDocs for project documentation

[marcospereira]

What?

tl;dr

Use MkDocs, Material for MkDocs, and mike to write, publish, and version the docs.

Current state

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

How it works

I will add plenty of links here so that it can function as a reference later.

Overall

The docs are now searchable, versioned, offer light/dark modes, present code snippets for Java and Kotlin, have fast navigation, automatically generated table of contents, and a few other markup extensions.

It is Python Markdown with a few extensions enabled. Although there are differences between that and GFM, they are minor, and I thought it was easy to adapt, considering the live-edit experience offered by MkDocs.

Locally

Python 3 is a requirement to install MkDocs and its plugins. The packages to install (at the time of this writing) are:

• mkdocs-material: pip install mkdocs-material
• mkdocs-awesome-pages-plugin: pip install mkdocs-awesome-pages-plugin
• mkdocs-macros-plugin: pip install mkdocs-macros-plugin
• mkdocs-pom-parser-plugin: pip install mkdocs-pom-parser-plugin
• mike: pip install mike

Then, to run the docs locally, execute the following command:

mkdocs serve

This starts a server at http://localhost:8000/, and automatically watches and reloads the docs (the browser) as they change.

Publishing

There is a new workflow to publish the docs automatically on tag creation (for example, when publishing a new release). The workflow only runs for version tags:

on:
  push:
    tags:
      - '[0-9]+.[0-9]+.[0-9]+'

But it does everything. :-)

For example:

1. Manual step 1: Publish a release
2. Automatic step 2: step 1 triggers a workflow run that pushes to gh-pages branch
3. Automatic step 3: step 2 triggers a gh-pages deployment.

About mkdocs-macros

The mkdocs-macro plugins allow us to extend the markup with macros specific to the project. I'm reluctant to include it since the macros are written in Python, but it should be rare that one needs to edit it.

The decision was to remove the mkdocs-macros plugin. :-)

About mkdocs-pom-parser-plugin

This is quite useful and allows to reference the project version (defined in the pom.xml file) so that there is no need to edit the docs when publishing a new release. For example, we can have links such as:

Migrate from [JSP](https://github.com/casid/jte/tree/{{ POM_VERSION }}/jte-jsp-converter)

There are other ways to get the version, but I think this is more native to MkDocs.

Open questions/tasks?

• [x] Remove the macros plugin?
• [x] Configure Github Pages. See this comment for details.

[codecov[bot]]

Codecov Report

All modified lines are covered by tests :white_check_mark:

Comparison is base (d63a4ae) 91.22% compared to head (e0585db) 91.15%.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #288 +/- ## ============================================ - Coverage 91.22% 91.15% -0.07% + Complexity 1193 1192 -1 ============================================ Files 76 76 Lines 3121 3121 Branches 482 482 ============================================ - Hits 2847 2845 -2 - Misses 167 168 +1 - Partials 107 108 +1 ``` | [Files](https://app.codecov.io/gh/casid/jte/pull/288?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Andreas+Hager) | Coverage Δ | | |---|---|---| | [...e-runtime/src/main/java/gg/jte/TemplateEngine.java](https://app.codecov.io/gh/casid/jte/pull/288?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Andreas+Hager#diff-anRlLXJ1bnRpbWUvc3JjL21haW4vamF2YS9nZy9qdGUvVGVtcGxhdGVFbmdpbmUuamF2YQ==) | `94.01% <ø> (ø)` | | | [.../html/policy/PreventOutputInTagsAndAttributes.java](https://app.codecov.io/gh/casid/jte/pull/288?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Andreas+Hager#diff-anRlLXJ1bnRpbWUvc3JjL21haW4vamF2YS9nZy9qdGUvaHRtbC9wb2xpY3kvUHJldmVudE91dHB1dEluVGFnc0FuZEF0dHJpYnV0ZXMuamF2YQ==) | `100.00% <100.00%> (ø)` | | | [jte/src/main/java/gg/jte/compiler/ClassUtils.java](https://app.codecov.io/gh/casid/jte/pull/288?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Andreas+Hager#diff-anRlL3NyYy9tYWluL2phdmEvZ2cvanRlL2NvbXBpbGVyL0NsYXNzVXRpbHMuamF2YQ==) | `65.00% <100.00%> (ø)` | | ... and [1 file with indirect coverage changes](https://app.codecov.io/gh/casid/jte/pull/288/indirect-changes?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Andreas+Hager)

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[marcospereira]

Here are a few updates on this:

I've moved the contents in the modules' README.md files to the docs. Because of that, I thought creating a few sections for the docs would be good. The current state is like this:

https://github.com/casid/jte/assets/4576/a1b5bba3-6840-4c1f-b423-b4ba3011aa9b

It is quite easy to shuffle things around, though. See https://github.com/casid/jte/pull/288/files#diff-98d0f806abc9af24e6a7c545d3d77e8f9ad57643e27211d7a7b896113e420ed2R76-R95.

[marcospereira]

I'm quickly converting this to a draft so that I can try a new version of the publishing workflow. :-)

[marcospereira]

Alright, @casid. We got a winner!

https://github.com/marcospereira/jte/actions/runs/6569837520

Some tricky things to consider (it may be due to me messing around with GH Pages):

1. You have to configure Pages to deploy from a GitHub Actions workflow:
2. In the repository "Settings -> Environments", there should be a github-pages:
3. In my case, I had to add a "deployment tag rule" to allow tags in that "Environment":

After that, I created a new release, and everything worked as expected. :-)

[casid]

Awesome! I'm heading off to work now, but will merge this in the evening and will try to configure everything as needed to replace the current content on https://jte.gg.

[casid]

Sorry, it got a bit late yesterday.

@marcospereira I merged today and thanks to your instructions I got everything up and running. The new jte website is now live at https://jte.gg/

Thank you so much for your contribution! This is amazing and the documentation is now so much easier to consume than the big file before!

[marcospereira]

@marcospereira I merged today and thanks to your instructions I got everything up and running. The new jte website is now live at https://jte.gg/

Amazing! And thanks for the fixes after merging.

One thing that I noticed is that since the site was published from the main branch, it suggests a snapshot version here:

https://jte.gg/#getting-started

And that version is used in other places too. I will check later if there is a way to use the latest release/tag instead of the pom version. There are a few other minor things I would like to change/add, so maybe I can bundle them all together. :-)

[marcospereira]

One thing that I noticed is that since the site was published from the main branch

Oh, and about this, cutting a new release would be good to both validate the workflow, and also have #285 out of the door. But it is Friday, so no rush at all. :-)

[casid]

I just published a new release and everything worked smoothly! Thank you for your contributions to this :-) I've also added a bullet point about the new documentation to the release notes.