Thanks Jack! To your questions: 1. In addition to Hugo, I tried out Pelican and Gatsby. (“Tried out” meaning spent an afternoon fooling around with it)
Pelican felt easy to use but doing anything custom like a landing page required a lot of theme and site config customizations. The live reloading also felt sluggish once I added in all of the content. Gatsby seems really flexible and powerful but it requires some knowledge of React that could discourage some community contributions in the future. Hugo on the other hand, in a little over an hour I was able to get the site together with the landing page, and another hour the next day I had asciinema added and the versioned docs working via GitHub (all with no prior experience with the framework). I definitely could have either of the other frameworks misunderstood. Some other frameworks out there that I haven’t looked deeply into are Jekyll, Hexo, and Nuxt. If anyone has strong preferences for a particular framework, let me know and I can explore it further. 2. The “latest” site is a branch itself. We can actually create as many branches as we’d like and each would be deployed as a separate site. We would just have to update the releases section to include the relevant hrefs. One thing I forgot to mention is that PRs are also deployed and we could do something clever here like include a link in the PR template that links to how the PR changes looks fully deployed. 3. I was thinking we would keep a copy of the docs in the main iceberg repo where the main commits occur. As part of the iceberg version release process, the docs would be copied over to the iceberg-docs repo in a branch named after the release version. Hotfixes or typo corrections for previous versions could be done via pull requests directly to that branch in the iceberg-docs repo. That being said, I believe it’s possible to keep the docs in the same repo but it would require some magic that may feel somewhat fragile. For example the branch names such as 0.12.x wouldn’t work well if we want to have a different docs site for 0.12.0 and 0.12.1, we could probably work around this by adding some kind of regex to the deploy workflow and maybe use tags ( https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet ). -Sam On Sat, Nov 27, 2021 at 5:59 PM Jack Ye <yezhao...@gmail.com> wrote: > The website looks amazing, thanks for the work!!! > > Some questions I have: > 1. you mentioned that you compared a few different static site frameworks. > Just for bookkeeping purposes, could you list what frameworks you have > compared so that people can have more clarity over the decision for hugo? > 2. In the website, I see the latest doc points to 0.12.1. Is it possible > to have a version named "Next" that shows the latest doc in the master > branch? > 3. For the separation of docs to another repo, I remember we discussed the > topic in the past and we decided to not do it because many people expressed > that it's valuable for docs to be in the same repo so that they can easily > view and edit it. Given that we now have the iceberg-docs repo, do we plan > to run a sync job to copy the docs to that repo, or are you thinking about > revisiting the decision to fully move the docs to iceberg-docs? It would be > helpful if you can provide more details in this area. > > Best, > Jack Ye > > On Sat, Nov 27, 2021 at 8:52 AM Sam Redai <s...@tabular.io> wrote: > >> Hey everyone, >> >> I wanted to bring to everyone's attention an issue that I opened today >> that's a proposal for switching to using hugo for the iceberg documentation >> site. https://github.com/apache/iceberg/issues/3616 >> >> I've deployed a prototype of what the site would look like and how it >> achieves some things still left desired for the current docs site (landing >> page, branch based versioning, etc). Please check it out when you have a >> chance and let me know what you all think! >> https://samredai.github.io/iceberg-docs-prototype/latest/ >> >> -Sam >> >
