bitsondatadev commented on code in PR #8659: URL: https://github.com/apache/iceberg/pull/8659#discussion_r1341864902
########## docs-new/README.md: ########## @@ -0,0 +1,123 @@ +<!-- + - Licensed to the Apache Software Foundation (ASF) under one or more + - contributor license agreements. See the NOTICE file distributed with + - this work for additional information regarding copyright ownership. + - The ASF licenses this file to You under the Apache License, Version 2.0 + - (the "License"); you may not use this file except in compliance with + - the License. You may obtain a copy of the License at + - + - http://www.apache.org/licenses/LICENSE-2.0 + - + - Unless required by applicable law or agreed to in writing, software + - distributed under the License is distributed on an "AS IS" BASIS, + - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + - See the License for the specific language governing permissions and + - limitations under the License. + --> + +# making-iceberg-docs + +Testbed for the Iceberg docs. + +## Requirements + +* Python >=3.9 +* pip + + +## Build process + +The directory structure is intended to mimic the tree hierarchy of the website. This will enable contributors to find the documentation they need to update easier. The static and documentation will reside in the same location. + +All static pages are all the `./home/.*md` files and the docs are the `.home/docs/<version>/*.md` files. Notice the location of the `mkdocs.yml`. + +Looking at this though, you may ask where the older versions and javadocs are. + +``` +. +├── home +│ ├── assets +│ │ └── images +│ ├── docs +│ │ └── latest +│ │ ├── assets +│ │ ├── api.md +│ │ ├── aws.md +│ │ ├── branching.md +│ │ ├── ... +│ │ ├── **mkdocs.yml(docs)** +│ │ ├── ... +│ │ ├── spark-structured-streaming.md +│ │ ├── spark-writes.md +│ │ └── table-migration.md +│ ├── ASF.md +│ ├── about.md +│ ├── ... +│ ├── vendors.md +│ └── view-spec.md +├── LICENSE +├── README.md +├── **mkdocs.yml(static)** +├── requirements.txt +└── variables.yml +``` + +All of the documentation versions are saved in special `docs-<version>` tags that only contain the root of the docs version they contian. There is also a `javadoc` tag that contains all prior versions of the javadocs in a single tag. These are generated and loaded only at build time using the [git-worktree](https://git-scm.com/docs/git-worktree) docs. Review Comment: Good question. It's complicated. First, docs url path and javadocs url path are in different locations, so they each have their own mount path when considering we use git worktree to pull the different versions together at build time. So the git worktree will mount whatever is in the tag at a given subdirectory. My initial plan was actually to do git worktree and [git sparse checkout](https://git-scm.com/docs/git-sparse-checkout) to define specifically what sections of the tag or remote tag I needed and place them in the proper points in the docs. This would allow me the flexibility to just define a tag per version that includes Java docs and Iceberg versioned docs. However, I was unable to get sparse checkout to work properly with worktree and I also noticed this in the docs: > THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE FUTURE. So instead I need the tags to contain the exact directory at the root that needs to be mounted for the docs. So that's what my deploy script handles. Now there's some debate we can have on how we want to do this. - If someone is a git wizard and can help me understand the behavior of worktree in tandem with sparse checkout, I'm happy to dig back into that if we think the future changes won't be disruptive but I doubt that's the path we want to take. - We can also consider sticking all docs and Javadocs into a single tag and just update that tag. - We could pair docs and javadocs into a tag together and every time I add a worktree, I'll have another part of the script that moves javadocs to the correct location. - Just do what we're doing now. I'm fine with any of these approaches really. I just chose the current one thinking it would make things easier to build from older versions. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org For additional commands, e-mail: issues-h...@iceberg.apache.org
