Add last updated to each page beneath title based on git commit

[tanishiking]

fix #3519

(Previously this PR is twofold: changing theme to furo + Add "Last Updated", but after some conversations we decided to focus on the latter one for the time being)

If introducing a different theme (furo) is controversial, I can split a PR into two (Add "Last updated" beneath the page title + furo theme)

Add "Last updated" beneath the page title to each page

Using mgeier/sphinx-last-updated-by-git: ⌚ Get the "last updated" time for each Sphinx page from Git and a little bit of JavaScript, each page has a Last Updated based on the git commit history beneath the page title.

The built HTML is available last-updated.zip

this will fix part of #3392

Old description

Introduces Furo sphinx theme

We'd been using the default sphinx theme sphinx-doc/alabaster which is mature good old sphinx theme. (I feel like it's old vive has a good fit with scala-native's logo brand 😄 ), but unfortunately there's a few issues with it

• Poor mobile support: I sometimes browse docs on my phone :)
  • It's not responsive enough: Alabaster is basically a responsive design, but scrolling is still required to read text on the right-hand side of the screen
    • 
  • There's no TOC until the footer
    • TOC is available on left sidebar on PC, but with phone, it's available only in footer, which makes it hard to navigate the docs on a phone.
• There're no backward and forward links between pages
  • Currently, we put the links by hand, but it's available only in a few pages Create native code page and add forward links by ekrich · Pull Request #3462 · scala-native/scala-native.
• Dark mode is not available

The good alternatives I know of are pradyunsg/furo, readthedocs/sphinx_rtd_theme, and pydata/pydata-sphinx-theme (They're the most starred sphinx theme on github https://github.com/topics/sphinx-theme). All of them looks better than Alabaster, but I'd like to recommend furo because

• sphinx_rtd_theme doesn't have dark theme
• pydata-sphinx-theme gives quite a lot of customizability to us User Guide — PyData Theme documentation, which seems too much for us
  • also it doesn't looks good in scala-native by default 😃
    • 
• furo solves the all the issues I have + it provides simple but enough customizability + I like it's minimal design

galleries

Screen.Recording.2023-10-02.at.10.48.47.mov

Test by yourself

• check out this branch
• ./scripts/makedocs setup
• ./scripts/makedocs

[tanishiking]

build-docs CI runs the sphinx build on sphinx-build-action, (which I made when I wasn't much familiar with this repository), but we can just run ./scripts/makedocs on CI 😄 otherwise we have to manage the dependencies for Sphinx build on ./scripts/makedocs and the github action.

I'm wondering how readthedocs will build the doc, does it use ./scripts/makedocs? readthedocs builds based on .readthedocs.yml which is available on 0.4 branch, we need to upstream to main too.

[ekrich]

Now that you removed the "continue to next page", is that generated for you?

[ekrich]

I wanted to rework the docs before but just haven't found time. See #2529

I really think a scaladoc 3 with a site would be the way to go - This is more work but I think rst could be converted to md and then we could also include all the scaladoc too.

[tanishiking]

Now that you removed the "continue to next page", is that generated for you?

yes 👍

I'm not sure how scaladoc can replace the website, but regarding the rst to markdown, we can do that in sphinx using the myst plugin
but if we could take time to rework the doc from sphinx to docsaurus or something, that's good to go 👍

[keynmol]

but if we could take time to rework the doc from sphinx to docsaurus or something, that's good to go 👍

I actually did something similar a while back :D I think I just used pandoc.

#2529 (comment)

[ekrich]

Scaladoc 3 can do static sites and the project scaladoc can be integrated.
https://docs.scala-lang.org/scala3/guides/scaladoc/static-site.html

I think the results is very nice and there is a chance if we support the project, it could improve.
Example: https://dotty.epfl.ch/

[tanishiking]

The documentation built by Docusaurus looks great, and the migration seems easy. We would just need to convert the documentation to Markdown, configure a few plugins and scripts, deploy it to GitHub Pages, and change the scala-native.org domain to point to the new page. I'm not sure who manages the domain, but once we find out, that should be easy to do.
I'm embarrassed to say that I didn't know about Scaladoc3's documentation generation functionality, but I think it's a great idea to use Scala tools to document Scala tools 👍

By the way, the most important change in this pull request is not the theme change to Furo, but the addition of the last modified date of the documentation to the head of the documentation.
In Docusaurus, it would be possible to display the last updated date at the bottom of the page with the showLastUpdated plugin. We could also adjust the display position with a custom script. I'm not sure about Scaladoc, but it shouldn't be impossible. If necessary, we can contribute to Scaladoc to add this feature.

Those options seem very attractive, but what do you think about discussing which of the two changes (introduction of Furo and display of last-modified date) to include or not in this pull request for the time being? We can also discuss the long-term documentation plan in #2529.
(Perhaps you don't want to change the theme if you plan to move the documentation to another platform such as Docusaurus or Scaladoc3, since frequent design changes to the documentation may confuse users.)

[LeeTibbert]

@tanishiking Since you asked...

1. I suggest splitting this PR into 2. One dealing with the "last updated" and the other with the "furo" theme.

2. I would have to see sample output (which may be above if I could slow down and read carefully) but
   my first thought would be to prefer the date at the top of the page rather than at the bottom. I have
   been taught to present the most important information first. Given the rate of change in SN, certainly
   the date of a statement is important in evaluating it.

   Perhaps I have been conditioned by Google & StackOverflow to always check the date of an info before
   acting on it.

   Either top or bottom is orders of magnitude better than no date.

   Being able to have the GitHub "last commit" date for the document, in either place, would be a big win.

3. When I have a chance, I will check the alternate "furo" theme. Times change and projects need to follow at
   a considered pace.

[tanishiking]

Thanks @LeeTibbert

I suggest splitting this PR into 2. One dealing with the "last updated" and the other with the "furo" theme.

Yeah, that seems better to move on, I'll make this PR to focus on the "last updated" thing, and make another PR for theme stuffs.

I would have to see sample output (which may be above if I could slow down and read carefully)
Perhaps I have been conditioned by Google & StackOverflow to always check the date of an info before
acting on it.

There is in the PR description #3520 (comment) and we have it on the top of the page (beneath the page title).
I also prefer having the date at the top of article also conditioned by StackOverflow or other blog platforms, and always check the information is up to date or not 😄

When I have a chance, I will check the alternate "furo" theme. Times change and projects need to follow at
a considered pace.

Gotcha, I'll build with at least 3 alternatives and upload the HTML files + screenshot in another PR 👍

---

It may take some time since I might be away from computer until next Tuesday

[tanishiking]

At least I updated this PR to remove theme related change + updated the description :)
Regarding the theme change, I'll open another PR. This PR is now ready for review.

[tanishiking]

It seems it's not reflected on https://scala-native.org/en/latest/ even though we have .readthedocs.yml on main branch, maybe we need to configure something on Read the docs side?

[WojciechMazur]

The scala-native.org should be correclty showing the new version of scaladoc. Now the latest version points to version build from main branch. However, still the default version is stable which points to 0.4.14 (0.4.15 failed to build due to missing .readthedocs.yml, can't fix it)

[tanishiking]

Oh, right. Indeed https://scala-native.org/en/latest/ have the ones 👍

[LeeTibbert]

@tanishiking

You are invited to the parade the local town square in celebration & thanksgiving for this one,
complete with marching brass band.

I think a welcome byproduct of the original Issue is that the 0.5.0-SNAPSHOT is now getting
published (as "latest") in a timely manner. Progress comes in small steps. To my thinking,
the "face" that Scala Native presents on ReadTheDocs now better represents all the hard work, recent
and past, which has gone into Scala Native.