Okay, so as I understand it, it seems like the current state of the docs is not ideal but satisfactory. The fact that we don't have a very strong demand for some new feature or a problem that would require a new doc engine means that we aren't yet ready to invest into a new engine or using mike for MkDocs.
On Tue, May 26, 2026 at 10:22 AM Kevin Liu <[email protected]> wrote: > > Thanks for starting this thread, Max. > > MkDocs is indeed abandoned. We get a warning message about it during building > the docs. However, we pin to and still use an older version of it. It gets > the job done :) > > With regards to versioned docs, I opened the issue [1] to explore `mike`. It > can potentially help us simplify the docs deployment process. However, it > does seem like a really big lift. Given the recent improvements to the > overall docs process, it might not be worth it to migrate to `mike`. > > As for the versioned dropdown, I really like the idea. But again, it might > not be worth the effort. Users can already navigate to older versions of the > doc [2] > > Best, > Kevin Liu > > [1] https://github.com/apache/iceberg/issues/14521 > [2] https://iceberg.apache.org/docs/1.10.2/ > > On Mon, May 25, 2026 at 4:36 PM Max Konstantinov > <[email protected]> wrote: >> >> > Can you explain more about what’s missing from our versioned docs? We can >> > get some documentation from prior releases (example: >> > https://iceberg.apache.org/docs/1.9.2/configuration/). The bug you >> > mentioned was about some issues with over-indexing, but it sounds like >> > those have been solved. >> >> Oh, yes, let me clarify. By versioned docs I meant the one with a >> dropdown selector that switches the current version of the docs, that >> idea surfaced in that email thread I referenced and current related >> issue propose to use mike for it. >> >> > I personally would love to move towards a different documentation engine, >> > but it’s a lot of work! I think the community would need really strong use >> > cases that we couldn’t easily support in mkdocs to attempt a migration. >> > Any ideas? >> >> I started looking into mike integration, which would enable the >> dropdown selector but then realized that mike is based on MkDocs and >> wanted to make sure that the effort put into mike integration won't be >> a waste. Atm I'm trying to understand our stance on adding new docs >> related features considering the fact that Iceberg's current >> documentation engine, MkDocs, is being abandoned. >> >> >> On Mon, May 25, 2026 at 3:58 PM Alex Stephen via dev >> <[email protected]> wrote: >> > >> > Hi Max, >> > >> > Thanks for kicking off this conversation! >> > >> > Can you explain more about what’s missing from our versioned docs? We can >> > get some documentation from prior releases (example: >> > https://iceberg.apache.org/docs/1.9.2/configuration/). The bug you >> > mentioned was about some issues with over-indexing, but it sounds like >> > those have been solved. >> > >> > I tried using mike for iceberg-python and came back frustrated. The mike >> > CLI is very opinionated and wants to make commits for you (‘mike deploy’). >> > This ended up not working well in our use-case. >> > >> > I personally would love to move towards a different documentation engine, >> > but it’s a lot of work! I think the community would need really strong use >> > cases that we couldn’t easily support in mkdocs to attempt a migration. >> > Any ideas? >> > >> > Thanks! >> > — Alex Stephen >> > >> > On Mon, May 25, 2026 at 2:48 PM Max Konstantinov >> > <[email protected]> wrote: >> >> >> >> Hi All! >> >> >> >> >> >> Background >> >> - MkDocs community has broken down over the last couple of years, and the >> >> project seems abandoned. You can see 0 new contributions during the last >> >> 1.5 years: >> >> https://github.com/mkdocs/mkdocs/graphs/contributors?from=5%2F18%2F2024. >> >> You can find the description and discussion of the whole kerfuffle on >> >> HackerNews' thread from March 2026 if you are interested, all previous >> >> maintainers moved on to new projects. >> >> - Iceberg community wanted to add versioned docs support to the Iceberg >> >> website, see a recent thread where the need for versioned docs surfaced a >> >> week ago: >> >> https://lists.apache.org/thread/vrt3oytl3dwo34wr07tkf73r0kkx0b1h. >> >> >> >> Questions >> >> - Do you think it is still worth pursuing mike route for versioned docs >> >> as it is based on MkDocs? See a related Iceberg issue: >> >> https://github.com/apache/iceberg/issues/14521 >> >> - Do you think we should look for a new doc engine altogether instead of >> >> MkDocs? >> >> >> >> >> >> Thanks, >> >> Max. >> >>
