+1 to Jekyll. I'm using it for another day job project. It's not perfect but I think the pros outweigh the cons. -Andy
On Tue, Jun 5, 2018 at 12:59 PM Josh Thompson <josh_thomp...@ncsu.edu> wrote: > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA1 > > I figured out the process to have a job on the ASF Jenkins server that > will > build from a branch to generate documentation using Jekyll. Things are > currently set up to build from a branch named "documentation". The > Jenkins > job automatically commits any changes to the generated html to the > asf-site- > test branch. The Jenkins job is currently set to run every 30 minutes. > > If we want to stick with this method, once we have enough documentation > converted, we can change the branch containing the generated html to > asf-site > (instead of asf-site-test) and ask the Infrastructure group to move > vcl.apache.org to be backed by that branch instead of subversion. > > Contributions to documentation from non committers can be handled by using > GitHub pull requests. > > Josh > > On Wednesday, May 30, 2018 2:46:28 PM EDT you wrote: > > Hi all, > > > > Our documentation is currently somewhat scattered and not very well > > organized. Before the 2.5 release, we tried to make an effort to get it > > more organized and updated, but didn't finish the job. We've had > > documentation split between 2 Confluence sites and the Apache CMS. > > Confluence provides a nice way to edit content, but doesn't show up at > > vcl.apache.org. The CMS is not as easy to edit, but does show up at > > vcl.apache.org. > > > > Now that we are switched over to Git, I'd like to explore the > possibility of > > moving to GitHub pages for documentation (or at least using markdown and > > Jekyll). From my currently limited understanding, GitHub pages uses a > > markdown format, pages can be edited directly through the GitHub web > site, > > and the markdown is compiled into HTML using Jekyll. > > > > What I'm not sure about yet is the integration between GitHub and ASF > Git. > > > > On the ASF side, it sounds like we need two additional branches in Git - > a > > name we come up with such as "documentation" that contains the markdown > > files, and "asf-site" that contains the Jekyll generated content. > However, > > the "documentation" branch may need to be named something like "gh-pages" > > for GitHub integration purposes. > > > > The Apache Infrastructure team has started exploring this further [1][2] > and > > creating some documentation, but haven't really written up anything yet. > > > > They do have a brief page explaining how the "asf-site" branch works. [3] > > > > There are a few other projects using Jekyll to generate content linked to > > from the [1] thread. Zookeeper has a good write up [4] on how to manually > > use Jekyll to generate the content and then commit that to Git. > > > > The OpenWhisk project has a response in the [1] thread explaining how > they > > use Jenkins to automatically run Jekyll and push its output to their > > asf-site branch. > > > > What I'd really like to figure out is a way to use the GitHub web site to > > edit content, then issue a pull request to the the content committed to > the > > ASF Git repo. Accepting the pull request would then commit the change to > > ASF Git which would trigger Jenkins to run Jekyll and commit the > generated > > content to the asf-site branch. > > > > What are others thoughts on this? > > > > Thanks, > > Josh > > > > [1] > > > https://lists.apache.org/thread.html/%3CB26A2265-5886-4324-A61F-F21E1CC1A2C > > 6...@apache.org%3E [2] > > > https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=75964385 > > [3] https://blogs.apache.org/infra/entry/git_based_websites_available > [4] > > https://cwiki.apache.org/confluence/display/ZOOKEEPER/WebSiteSetup -- > > ------------------------------- > > Josh Thompson > > VCL Developer > > North Carolina State University > > > > my GPG/PGP key can be found at pgp.mit.edu > > > > All electronic mail messages in connection with State business which > > are sent to or received by this account are subject to the NC Public > > Records Law and may be disclosed to third parties. > - -- > - ------------------------------- > Josh Thompson > VCL Developer > North Carolina State University > > my GPG/PGP key can be found at pgp.mit.edu > > All electronic mail messages in connection with State business which > are sent to or received by this account are subject to the NC Public > Records Law and may be disclosed to third parties. > -----BEGIN PGP SIGNATURE----- > > iF0EARECAB0WIQRMIdRtWXideTZDK31X8tBw1209AwUCWxbBFwAKCRBX8tBw1209 > A2t/AJ0SkKZ6Y7l2sL7k/wRxzw34xpz1OACfZp9+ShlbMVU+gIBQCx/3oKFU6GY= > =k7kX > -----END PGP SIGNATURE----- > > > > -- *Andy Kurth* Research Storage Specialist NC State University Office of Information Technology P: 919-513-4090 311A Hillsborough Building Campus Box 7109 Raleigh, NC 27695
