Diffa Diffa

Comments and changes to this ticket

• You flagged this item as spam.
  

  Michal Cudrnak September 27th, 2010 @ 04:33 PM

  • State changed from “new” to “open”

  So rendering it from the latest gh-pages should do the job, right? (i.e. with no Jekyll involved) Copying Jekyll-generated content to gh-pages and pushing onto that branch is a mandatory step anyway.

• 

  Ben Hood September 27th, 2010 @ 11:27 PM

  Sorry, I don't follow. Are you saying that we have to stage and commit
  the output from Jekyll? That surprises me a bit - I would have thought
  that a post commit hook in Github would invoke the compilation on
  their server - is this not the case?

  To be clear, the reason why I wanted to put it onto TC was to

  • sanity check the compilation before it gets pushed to the public gh-pages branch

  • let people review it internally on TC as a staging server without them having to compile it themselves

• You flagged this item as spam.
  

  Michal Cudrnak September 27th, 2010 @ 11:45 PM

  Oh dear, what I wrote really makes no sense. When I said Jekyll I actually meant the docgen plugin. To clarify:

  If you want to build new docs you do the following:
  1. Modify docgen & generate new REST API docs into gh-pages.
  2. Edit any static files in gh-pages where necessary.
  3. Compile website with Jekyll to test
  4. Push your changes on master and gh-pages.

  Now for my question: Should the TC goal run the docgen plugin as in step 1? I presume not. It should just run Jekyll from the current gh-pages, correct?

• 

  Ben Hood September 28th, 2010 @ 07:20 AM

  The short answer to your question is yes, the TC configuration should
  only run Jeykll. We will assume that the docgen has been run manually.

  There are still a couple of things that could be clearer in the approach:

  • You don't necessarily need to regenerate the REST doc if it hasn't changed. This is the part of the approach I don't like because it
    relies on a manual step, but for now I don't see a realistic
    alternative.

  • If however you do make a change to the code base that necessitates a regeneration, then this must be pushed to gh-pages. I would have
    thought that the underlying changes that precipitated the regeneration
    would get committed as part of the normal dev process.

  • Any changes to static pages will be committed to gh-pages (for now - see point 5)

  • You want to have TC compile and serve on each commit to gh-pages. Whether or not you run the compilation first on your local copy is up
    to you. Generally it is an advisable step because we don't yet have
    any staging yet.

  • Going forwards we should start this staging branch and point TC at it.

• You flagged this item as spam.
  

  Michal Cudrnak September 29th, 2010 @ 03:08 PM

  • State changed from “open” to “resolved”

  Added to TC as an archive. (Directory would be useless because the website relies on absolute paths on the web server)

• 

  Ben Hood September 29th, 2010 @ 03:15 PM

  • State changed from “resolved” to “open”

  Nice work, but producing the archive was just the cherry on top - the main task was to publish a normal (i.e. exploded) doc tree that those who have access to TC can just click on, hence reopening :-)

• You flagged this item as spam.
  

  Michal Cudrnak September 29th, 2010 @ 03:37 PM

  • State changed from “open” to “resolved”

  I've added an exploded tree as well. However, as I outlined in my previous post browsing through links won't work on TC. We could build the site so that it doesn't rely on this but we'd have to hardcode some path features in the REST docgen (specifically, the depth from / to /rest/doc to be 2) or change the code such that it calculates the depth of /rest/doc (or whatever the target dir is set to).

  Strategy?

• 

  Ben Hood November 17th, 2010 @ 02:38 PM

  • State changed from “resolved” to “open”
  • Assigned user cleared.

  I'm re-opening this because publication doesn't yet work on TC.