Sounds good to me. To Confirm point 3: We have unpublished version docs in Iceberg repo proper, and released version doc fixes target the new repository.
> On Nov 29, 2021, at 4: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 > <mailto: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 > <mailto: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 > > <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 > <mailto: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 > <mailto: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 > <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/ > <https://samredai.github.io/iceberg-docs-prototype/latest/> > > -Sam > > > -- > Ryan Blue > Tabular
