Div | ||
---|---|---|
| ||
RFC-10: Restructuring and auto-generation of docs |
Table of Contents |
---|
Proposers
Approvers
- Vinoth Chandar : [APPROVED/REQUESTED_INFO/REJECTED]
- Balaji Varadarajan : [APPROVED/REQUESTED_INFO/REJECTED]
Status
Current state:Under Discussion Status colour Yellow title In progress
Discussion thread: here
JIRA:here Jira server ASF JIRA serverId 5aa69414-a9e9-3523-82ec-879b028fb15b key HUDI-504
Released: <Hudi Version>
Abstract
This RFC aims at 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:
Implementation
<Describe the new thing you want to do in appropriate detail, how it fits into the project architecture. Provide a detailed description of how you intend to implement this feature.This may be fairly extensive and have large subsections of its own. Or it may be a few sentences. Use judgement based on the scope of the change.>
Rollout/Adoption Plan
- <What impact (if any) will there be on existing users?>
- <If we are changing behavior how will we phase out the older behavior?>
- <If we need special migration tools, describe them here.>
- <When will we remove the existing behavior?>
Test Plan
- 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. Migration with Travis-ci, it can build the asf-site branch and execute callback scripts.
The diagram below shows the workflow.
Key Points
There are several key points need to consider:
- How to migration with travis-ci
- How to use git command safely in travis-ci (important)
To use git command safely, hidden the password, we need use bellow form.
Code Block | ||
---|---|---|
| ||
git clone https://${GIT_TOKEN}@github.com/${GIT_REPO}/${GIT_PROJECT}.git |
Steps to get the {GIT_TOKEN}
Steps - 01 : Enable two-factor authentication
https://help.github.com/en/github/authenticating-to-github/about-two-factor-authentication
Steps - 02 : Generate personal access tokens
Steps to migration with travis-ci
Steps - 01 : Active repository
Steps - 02 : Add {GIT_TOKEN} to environment variables
Steps - 03 : Add .travis.yml file to asf-site branch
Code Block | ||
---|---|---|
| ||
language: ruby
rvm:
- 2.6.3
git:
clone: false
env:
global:
- GIT_USER="CI BOT"
- GIT_EMAIL="cibot@test.com"
- GIT_REPO="apache"
- GIT_PROJECT="incubator-hudi"
- GIT_BRANCH="asf-site"
- DOCS_ROOT="`pwd`/${GIT_PROJECT}/docs"
before_install:
- git config --global user.name ${GIT_USER}
- git config --global user.email ${GIT_EMAIL}
- git clone https://${GIT_TOKEN}@github.com/${GIT_REPO}/${GIT_PROJECT}.git
- cd ${GIT_PROJECT} && git checkout ${GIT_BRANCH}
- gem install bundler:2.0.2
script:
- pushd ${DOCS_ROOT}
- bundle install
- bundle update --bundler
- bundle exec jekyll build _config.yml --source . --destination _site
- popd
after_success:
- \cp -rf ${DOCS_ROOT}/_site/* test-content
- git add -A
- git commit -am "Travis CI build asf-site"
- git push origin asf-site --force
branches:
only:
- asf-site |
Steps - 04 : Check whether ci works well or not
End
Hope, this will works well
Test
had test https://github.com/lamber-ken/lamber-ken.github.io, when commits, it will generate docs and push the content to asf-site branch.
<Describe in few sentences how the RFC will be tested. How will we know that the implementation works as expected? How will we know nothing broke?>