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
