Hey All, I know it's been a while but the first phase of the docs refactor has landed. I think it's at a decent point for everyone to take a look. To be clear, this is not going to replace the existing website yet, but get the first large landing of new docs to provide the initial proof of concept for the build and make incremental changes until we are comfortable making the swap. Once this is in and 1.4.0 goes out, I'll have to retroactively create tags for each prior version of the documentation. While that's happening, we can have someone else work on the look and feel of the website, to look closer to our current site.
https://github.com/apache/iceberg/pull/8659 Thanks! Let me know if you have any questions! - Bits On Thu, Jul 27, 2023 at 4:10 PM Szehon Ho <szehon.apa...@gmail.com> wrote: > Hi > > I'm ok with putting things back in Iceberg repo, it gets more visbility > on prs. I guess it used to be a bit distracting, but now with more > projects in Iceberg (pyiceberg, rust) we have to anyway use tags to filter > through all the mails. > > Just wanted to +1 on Fokko/Ryan suggestion to avoid versioned doc > directories, I had a lot of difficulties in this part doing the last > release: https://github.com/apache/iceberg/issues/8151 , as did Anton > when I consulted him offline. > > For me, replacing the 'latest' branch with a tag would be the biggest win > as it caused me the most trouble. If we can avoid versioned docs and use > tags across the board, that would be even better, I do think all the > versions are already tagged in Github on every release, if that is your > question? > > Thanks, > Szehon > > On Thu, Jul 27, 2023 at 2:31 AM Brian Olsen <bitsondata...@gmail.com> > wrote: > >> Thanks Fokko, >> >> Yeah, I think tío address that we would need to switch to a tagging that >> prefixes the different project name as a namespace within the tags space >> (e.g. pyIceberg-0.4.0, rust-0.0.1, etc…). But certainly this would result >> in an explosion of tags as we continue to introduce more projects. I’m not >> sure if this makes it difficult to find things as long as you start to >> search the prefix in GitHub it should be easy enough to find. Has anyone >> else worked on a project where this type of tagging is applied? Are their >> any performance, searching, or other implications we are missing? >> >> Bits >> >> On Thu, Jul 27, 2023 at 4:18 AM Fokko Driesprong <fo...@apache.org> >> wrote: >> >>> Hey Brian, >>> >>> Thanks for raising this. As a release manager, I can confirm that the >>> current structure is confusing, and I can also see the community >>> struggling with this because they are willing to contribute to the docs, >>> but cannot always find the place where to do this. I think the complexity >>> of the current website mostly comes from the versioned docs. It would be >>> great if we can find a way to make this easier. Instead of using the >>> branches, we could also use the release tags and build the docs for those >>> versions. >>> >>> I think switching to mkdocs-material is a great idea. We currently also >>> use this for PyIceberg, and it works really well. My main concern is around >>> merging everything together. Should we combine Java and Python in the same >>> documentation? They have a different versioning scheme, so that would >>> create a matrix of versions. Go and Rust >>> <https://github.com/apache/iceberg-rust/issues/8> is also in the >>> making, so that would explode at some point. >>> >>> Cheers, Fokko >>> >>> Ps. Currently, PyIceberg uses the gh-pages branch for publishing the >>> docs <https://github.com/apache/iceberg/tree/gh-pages>. >>> >>> >>> Op do 27 jul 2023 om 00:04 schreef Brian Olsen <bitsondata...@gmail.com >>> >: >>> >>>> Hey all, >>>> >>>> I have some proposals I'd like to make to fixing the docs. I would want >>>> to do this in two phases. >>>> >>>> The first phase I'm proposing that we locate all the documentation >>>> (reference docs, website, and pyIceberg) back into the apache/iceberg >>>> repository. I explain my reasoning in the attached document. This phase >>>> would also update us from Hugo to MkDocs but keep all the content the same. >>>> >>>> The second phase, is focused on iteratively building out the content >>>> that we've marked missing in some the proposal that Sam R. created along >>>> with a recent community member, Mahfuza. We will also restructure the >>>> content to following the diátaxis method (https://diataxis.fr/). >>>> >>>> >>>> https://docs.google.com/document/d/1WJXzcwC6isfoywcLY2lZ9gZN6i0JU1I2SIZmCkumbZc/edit#heading=h.gli9mc2ghfz1 >>>> >>>> Let me know what you think and bring on the questions and criticisms >>>> please! :) >>>> >>>> Bits >>>> >>>
