Proposers

• Ethan Guo
• lamber-ken

Approvers

• Vinoth Chandar  : [APPROVED/REQUESTED_INFO/REJECTED]
• Balaji Varadarajan  : [APPROVED/REQUESTED_INFO/REJECTED]

Status

Current state:  IN PROGRESS

Discussion thread: here

JIRA:  Unable to render Jira issues macro, execution error.

Released: <Hudi Version>

Abstract

This RFC aims at improving the Hudi web documentation for users and the process of updating docs for developers.

Background

There are a few gaps we observed regarding the docs:

• We only have one version of docs kept at the asf-site branch for the latest release.  Given that each version has new features and improvements, some involving configuration and parameter changes compared to to previous versions, the single version of docs can create confusion for users using a previous release of Hudi.
• There's no API docs generated from the code.
• Current process of building, testing, and deploying docs (i.e the content powering hudi.apache.org) is mostly manual.

Implementation

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.

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. 

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