Bumpingn this thread again. Once we reciew and land the PR, it will be easy to make incremental changes to reflect new guidelines and docs tooling
On Tue, Feb 5, 2019 at 8:49 AM Vinoth Chandar <[email protected]> wrote: > Great points! Docker definitely could be useful to provide a standard > Jekyll, ruby build environment. > Something, that Nishith himself had trouble with. > > On Mon, Feb 4, 2019 at 7:09 AM Thomas Weise <[email protected]> wrote: > >> A pull request is the common way to propose changes in other projects, so >> that's good. >> >> One of the things you will want to work on going forward are contributor >> guidelines that explain this, among other things. >> >> Other suggestions (that can all be taken up as follow-up, perhaps worth >> creating a JIRAs): >> - Source file should have license headers >> - Take a look at other incubator and top level projects for web site >> commonalities such as community / contributing sections >> - Consider adding a README to the web site sources folder and a build >> script that shields developers from error prone manual steps >> - Docker is a good way to avoid having to install pieces on the host OS >> (example: >> >> https://flink.apache.org/improve-website.html#update-or-extend-the-documentation >> ) >> - Maybe in the future you want to separate web site sources from >> documentation (since documentation is usually specific to versions) >> >> Thomas >> >> >> >> On Sun, Feb 3, 2019 at 11:05 PM nishith agarwal <[email protected]> >> wrote: >> >> > Hi All, >> > >> > I've altered the documentation and created a PR against the "asf-site" >> > branch due to absence of a master branch (instead of pushing to a branch >> > directly). In the comments, I've tried to explain the changes I made. In >> > summary, most of our packages, metadata for datasets, admin client and >> more >> > are named with "hoodie". For now, I've just made some cosmetic name >> changes >> > in the docs from "hoodie" -> "hudi" since performing a widespread rename >> > does not make sense. >> > My guess is we can have an initial version of the site ready with such >> > changes, iterate on it and come up with a plan as we migrate the >> codebase >> > but I'd love to hear your thoughts around this. >> > >> > Thanks, >> > Nishith >> > >> > On Thu, Jan 31, 2019 at 2:38 PM nishith agarwal <[email protected]> >> > wrote: >> > >> > > Yes, I'll get to it later tonight. >> > > >> > > Thanks, >> > > Nishith >> > > >> > > On Thu, Jan 31, 2019 at 1:04 PM Vinoth Chandar <[email protected]> >> > wrote: >> > > >> > >> Nishith, are you working on the site? Just wanted to confirm and see >> if >> > >> you >> > >> need more help from one of us. >> > >> >> > >> On Thu, Jan 24, 2019 at 8:21 PM Vinoth Chandar < >> > >> [email protected]> wrote: >> > >> >> > >> > What thomas says, makes sense to me. For now, we can just import >> site >> > >> into >> > >> > asf-site and make a call on what we check into master down the >> line? >> > >> > >> > >> > On Thu, Jan 24, 2019 at 8:17 PM Vinoth Chandar < >> > >> > [email protected]> wrote: >> > >> > >> > >> >> Guess it does nt clutter source code with docs, js, css etc? >> > >> >> >> > >> >> On Thu, Jan 24, 2019 at 7:46 PM nishith agarwal < >> [email protected] >> > > >> > >> >> wrote: >> > >> >> >> > >> >>> I vote for #3 as well. Yes, I'll take up the lead on this. >> > >> >>> BTW, why is creating a separate branch (asf-site) so popular ? I >> see >> > >> that >> > >> >>> many projects have done that. >> > >> >>> >> > >> >>> Thanks, >> > >> >>> Nishith >> > >> >>> >> > >> >>> On Thu, Jan 24, 2019 at 2:13 PM Anbu Cheeralan < >> [email protected]> >> > >> >>> wrote: >> > >> >>> >> > >> >>> > I prefer #3 that will keep the documentation in-sync with the >> > code. >> > >> >>> > >> > >> >>> > On 2019/01/24 21:27:39, Vinoth Chandar < >> > >> [email protected]> >> > >> >>> > wrote: >> > >> >>> > > Hello all, >> > >> >>> > > >> > >> >>> > > Just summarizing how the current project documentation is >> setup >> > >> and >> > >> >>> then >> > >> >>> > > use this thread to discuss how we want to proceed. Its based >> on >> > >> >>> Jekyll >> > >> >>> > and >> > >> >>> > > markup.To build Hudi docs, you just need to install gem/ruby >> set >> > >> and >> > >> >>> spin >> > >> >>> > > up Jekyll. >> > >> >>> > > https://idratherbewriting.com/documentation-theme-jekyll/ >> has >> > >> >>> > > instructions. >> > >> >>> > > >> > >> >>> > > We have a few options to manage docs. >> > >> >>> > > >> > >> >>> > > 1. Separate repo (away from source code) >> > >> >>> > > 2. Special branch along with code (asf-site branch here >> > >> >>> > > https://github.com/apache/incubator-hudi ) >> > >> >>> > > 3. Checked into a top level docs folder on all branches >> (current >> > >> >>> > approach) >> > >> >>> > > >> > >> >>> > > I vote for #3. I have do #2 on a previous open source project >> > and >> > >> the >> > >> >>> > code >> > >> >>> > > kept diverging from docs. >> > >> >>> > > >> > >> >>> > > What do you all think? >> > >> >>> > > >> > >> >>> > > Nishith, can you confirm you are taking the lead on this? >> > >> >>> > > >> > >> >>> > > Thanks >> > >> >>> > > Vinoth >> > >> >>> > > >> > >> >>> > >> > >> >>> >> > >> >> >> > >> >> > > >> > >> >
