Absolutely, I’ll get that PR open before the end of the week! -Sam
On Tue, Nov 30, 2021 at 3:46 PM Ryan Blue <b...@tabular.io> wrote: > Sounds like we're in agreement on this plan. Thanks for all the work, Sam! > Is it possible to get a PR up against the docs repo with the initial front > page and then we'll build from there? > > On Tue, Nov 30, 2021 at 10:30 AM Jack Ye <yezhao...@gmail.com> wrote: > >> Sounds good! Looking forward to that! >> -Jack >> >> On Tue, Nov 30, 2021 at 10:27 AM Sam Redai <s...@tabular.io> wrote: >> >>> @Kyle thanks for the idea, we can definitely add that banner and have it >>> driven by a site level latest version value so it can easily be set on each >>> version release. >>> >>> @Jack that summary looks right to me. As to your idea of the "Next" >>> version of the docs and to Russell's description, we could absolutely have >>> an additional branch in the docs repo that reflects the next (yet to be >>> released) version of the docs. It would be as simple as including an aptly >>> named branch in the docs repo that always reflects the docs contained in >>> iceberg repo proper (possibly through some daily/weekly action). So the >>> branches in the iceberg docs repo could look something like this: >>> >>> - latest >>> - next >>> - 0.12.1 >>> - 0.12.0 >>> >>> latest can be set as the default branch for the repo and would >>> essentially be the result of a force push from 0.12.1 (and once 0.13.0 is >>> released, a force push from the 0.13.0 branch, and so on and so on). The >>> next branch could contain this next version that you were referring to, >>> which is periodically updated with the docs contained in iceberg repo >>> proper. As Ryan suggested, once a release happens, the docs can be copied >>> over into a branch for that version. This would result in the following >>> version routes: >>> >>> https://iceberg.apache.org/latest/docs >>> https://iceberg.apache.org/next/docs >>> https://iceberg.apache.org/0.12.1/docs >>> https://iceberg.apache.org/0.12.0/docs >>> >>> We could also include redirects to from / to /latest/docs in order to >>> not break permalinks. I'll work on getting all of this finalized and share >>> a full summary of how the new site works as well as some developer docs on >>> updating/releasing. >>> >>> -Sam >>> >>> On Mon, Nov 29, 2021 at 4:28 PM Russell Spitzer < >>> russell.spit...@gmail.com> wrote: >>> >>>> 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> >>>> 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 >>>> >>>> >>>> > > -- > Ryan Blue > Tabular >
