You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@vcl.apache.org by Josh Thompson <jo...@ncsu.edu> on 2018/06/05 16:57:59 UTC
Re: [DISCUSS] VCL documentation
-----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-----
Re: [DISCUSS] VCL documentation
Posted by Andy Kurth <an...@ncsu.edu>.
+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 <jo...@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