Infusion-docs with DocPad

[Bates, Simon]

Hi Tony,

We will be starting on the design work this week or next. We'll then need a bit of time to implement the design, so I would give it a couple of weeks or so.

I made a couple of updates to my DocPad version of the infusion-docs this week:

  *   Yesterday, I was reading the docs for the Ansible automation project (for work unrelated to our docs) and I noticed that they have on each doc page an "Edit on GitHub" link (such as http://docs.ansible.com/intro.html). Ansible has a similar setup to what we are working towards: docs in markup in GitHub with a rendered HTML version. In their case, they are using reStructuredText rather than Markdown, but it's the same idea. Each page's "Edit on GitHub" link takes you to the corresponding file in their GitHub repo. At this point GitHub offers a fairly nice flow -- you can edit on GitHub if you've got write access or it will clone the repo for you if you don't. So, I decided to implement something similar on my infusion-docs-docpad and pushed it yesterday afternoon. This gives us a easy way for people to contribute changes and makes the relationship between the rendered HTML and files in GitHub fairly transparent.
  *   I have also updated infusion-docs-docpad to grab the infusion-docs using a git submodule, rather than duplicating the doc files. This adds some more steps to anybody trying out the DocPad version -- grab the submodule, and run grunt to prepare the files -- but means that we can easily keep up to date with infusion-docs without the overhead of keeping the repos in synch. Once we move to DocPad we can remove this extra processing.

It feels like we are getting closer and I'm excited for the docs to be ready and to have them up as soon as we can.


Simon


________________________________
From: Tony Atkins [tony at raisingthefloor.org]
Sent: Wednesday, June 25, 2014 4:58 AM
To: Colin Clark
Cc: Bates, Simon; fluid-work at fluidproject.org
Subject: Re: Infusion-docs with DocPad

HI, All:

I have in the past often pointed out limitations in our documentation. As Justin and I work to implement the new CTR reviewer interface using FLUID components, I am excited to have an easier way to feed back changes and expand our documentation.  I hope that we move to DocPad sooner rather than later.  Is there a timeline for the design work?

Cheers,


Tony


On Sun, Jun 22, 2014 at 2:53 PM, Colin Clark <colinbdclark at gmail.com<mailto:colinbdclark at gmail.com>> wrote:
+1. This is a very sensible approach and it's going to be awesome when it's done.

Colin

On Jun 18, 2014, at 6:22 PM, Bates, Simon <sbates at ocadu.ca<mailto:sbates at ocadu.ca>> wrote:

> I'd like to propose the following path forward:
>
> 1. We continue our conversion process as we have been doing so far, adding docs to https://github.com/fluid-project/infusion-docs
> 2. In parallel, I will maintain the DocPad version of the docs at https://github.com/simonbates/infusion-docs-docpad which we will use for testing
> 3. We go ahead and start on some design and templating/styling for the docs
> 4. Once we are happy with the DocPad version of the docs, we update the main infusion-docs repo
>
> Please let me know if you have thoughts.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20140626/e99d2c72/attachment.html>