Wow, the prototype looks great, Sam! I'd like to add a little bit about possible avenues for hosting to explore and other corner areas.
I only have one thing to add: 1) For the latest docs, can we consider including a warning message on the page that this is for the master version. Apache Flink has this, and on several occasions it has helped me out. Their doc string reads: "This documentation is for an unreleased version of Apache Flink. We recommend you use the latest stable version <link to that version>". Overall the site looks great. Thank you, Sam! On Sun, Nov 28, 2021 at 11:03 PM Sam Redai <s...@tabular.io> wrote: > 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 >>> >>
