Table of Contents |
---|
Proposers
...
To address these gaps, restructuring of the docs is needed to make the process easier.
- Copy docs from asf-site to master branch
- Migration with Apache buildbot, it helps to build branchs and deploy website to https://ci.apache.org/projects/hudi/hudi-docs-XXX
- The diagram below shows the structuring and the workflow.
drawio
Branch configuration
The hudi.conf file mentioned above contains a hudi_branches_nightly variable that configures the branches to build nightly:
# format: (branch, alias) or branch
hudi_branches_nightly = [
('master', '0.5.2-SNAPSHOT'),
('release-1.5.1', 'stable'),
('release-1.5.0')
]
The docs will be served under the following URLs:
- https://ci.apache.org/projects/hudi/hudi-docs-BRANCH (e.g. hudi-docs-master)
- https://ci.apache.org/projects/hudi/hudi-docs-release-0.5.1
- https://ci.apache.org/projects/hudi/hudi-docs-release-0.5.0
File structure
Eventually, we will have all .md of docs files on master, thus allowing the docs change with code change to be committed in a single PR. The automation scripts to generate the docs content will also be on master. To start with, we still keep all docs files on a separate branch, i.e., asf-site.
Versioning docs
The documentation should evolve with the code changes. Thus, we need to version the docs regarding design, implementation details and API examples according to each release version. In this way, the code and the corresponding docs change can coexist in the same PR. Specific pages around these include:
- Quickstart
- Concepts
- Writing Data
- Querying Data
- Configuration
- Performance
- Administering
In addition to these content, a new set of API docs will be generated by javadoc for each release (similar to this).
Content regarding the general information of Hudi only have one version, generated from the latest changes:
- Use Cases
- Talks & Powered By
- Comparison
- Releases
- Community
- Code
- Developers
- Feedback
The docs content are still generated from a single branch, so that all page references can be generated properly. The generated web pages are then uploaded to the hosting server for the Hudi site. The landing page references the specific version of docs content through links.
For backward compatibility, we can manually generate the content for current (0.5.0-incubating) and one or two old releases (0.4.6/0.4.7), to fit into the new docs structure.
Automating docs update
To make updating and deploying docs content easier, a set of scripts automating the above process will be added (including sanity checks of whether there are breaking changes, e.g., broken links, missing pages, before actual changes to the site). In this way, once the changes to the /docs on either master or asf-site are landed, the update content pages can be uploaded to the hosting server of Hudi website.
Rollout/Adoption Plan
- No impact on existing users regarding APIs as this is docs website change.
Apache buildbot build branchs and deploy website to https://ci.apache.org/projects/hudi/hudi-docs-XXX nightly.
Note
- We need to keep asf-site as it is, asf-site is used for https://hudi.apache.org which always service for the latest stable release.
- Once PR to the docs at master branch merged, we can use buildbot to build the site manually or nightly, https://ci.apache.org/projects/hudi/hudi-docs-master.
- When a contributor submits a code change to the site, will not has the staging site.
Test Plan
- Test the content organization locally to make sure the links are working and the content is readable
Appendix
- Improvements and discussion on the content of the landing page are moved here