Yes this is definitely a win-win! The only thing unclear to me is how we handle the latest doc. Are we going to copy the doc from main to doc repo through something like a daily job?
-Jack On Mon, Nov 29, 2021 at 2:34 PM Ryan Blue <b...@tabular.io> wrote: > I think that what Sam has put together is a good path forward for the docs. > > We definitely want to keep the latest docs in the main repository so that > we can update them as part of normal pull requests. But at the same time, I > think we've all had some frustration when searching through files in the > repository because there are multiple copies of Javadocs there. And if we > wanted to keep more versions of the markdown docs, the problem would get > worse. > > By keeping just the docs that apply to master in the main iceberg repo, we > still have the normal maintenance workflow. Copying the docs over at > release time allows us to maintain each branch of docs separately for > updates, without polluting the main repo with several copies. It seems like > a win-win to me to copy docs and maintain them after that point. > > Does that seem reasonable to everyone? > > Ryan > > On Mon, Nov 29, 2021 at 8:54 AM Kyle Bendickson <k...@tabular.io> wrote: > >> 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 >>>>> >>>> > > -- > Ryan Blue > Tabular >
