[jira] [Commented] (SAMZA-259) Restructure documentation folders

["Yan Fang (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/SAMZA-259?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14082035#comment-14082035 ] 

Yan Fang commented on SAMZA-259:
--------------------------------

1,2,3 steps make sense.

In terms of 4, I feel we could do it in a simpler way (in the publish-site.sh):
1. get the branch/version name, that is, VERSIONED_BRANCHE. We can get this using ["git branch"|http://stackoverflow.com/questions/2111042/how-to-get-the-name-of-the-current-git-branch-into-a-variable-in-a-shell-script] , accepting argument or hard code. Hard code is also fine here because this is the only thing we need to change when we update the version or create new branch, just like we do in the "version" of gradle.properties.
2.  run generate-javadocs.sh, and bundle exec jekyll build
3. rename the "versioned" to VERSIONED_BRANCHE in _site
4. cp -r _site/* $SVN_TMP/site/

So by doing this, in master branch we will only update the master directories and will not update 0.7.0 directories. The same behavior happens in 0.7.0 branch. That is because when we do "cp", it only copies (and override) the directories with the same name, e.g. documentations/master will not influence documentations/0.7.0.

Will this make sense?


> Restructure documentation folders
> ---------------------------------
>
>                 Key: SAMZA-259
>                 URL: https://issues.apache.org/jira/browse/SAMZA-259
>             Project: Samza
>          Issue Type: Bug
>          Components: docs
>    Affects Versions: 0.6.0
>            Reporter: Chris Riccomini
>             Fix For: 0.8.0
>
>
> Currently, we have hard-coded versions in the documentation path. When we bump versions we have to manually create a new subfolder called 0.8.0, and update all links to point to this version. A better approach is probably do what [rust|http://www.rust-lang.org/] does: use branches to build multiple versions of documentation. We already have an 0.7.0 branch, and we've got master. This very much mirrors Rust's structure:
> http://static.rust-lang.org/doc/master/tutorial.html
> http://static.rust-lang.org/doc/0.10/tutorial.html
> This structure shouldn't change the paths in the website. All that it means is that we'll have:
> * http://samza.incubator.apache.org/startup/hello-samza/master/
> * http://samza.incubator.apache.org/startup/hello-samza/0.7.0/
> * http://samza.incubator.apache.org/learn/documentation/master/
> * http://samza.incubator.apache.org/learn/documentation/0.7.0/
> * http://samza.incubator.apache.org/learn/tutorials/master/
> * http://samza.incubator.apache.org/learn/tutorials/0.7.0/
> This is better for SEO, as well, since everyone will link to master, which will always reflect up-to-date information. With our current setup, everything that links to 0.7.0 will be outdated when we release docs with 0.8.0.



--
This message was sent by Atlassian JIRA
(v6.2#6252)