Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
Received-SPF: pass (athena.apache.org: domain of fil@adobe.com designates
 64.18.1.234 as permitted sender)
From: Filip Maj <fil@adobe.com>
To: "dev@cordova.apache.org" <dev@cordova.apache.org>
Date: Tue, 19 Feb 2013 16:51:39 -0800
Subject: Re: docs on cordova.apache.org
Thread-Topic: docs on cordova.apache.org
Thread-Index: Ac4PBHKcfI7lRajDT0GYhiXM3oyYfg==
Message-ID: <CD495E17.18215%fil@adobe.com>
In-Reply-To: 
 <CAP7NMPpeRg5vgX2JrNfjYvOuM8qFLC-V4SmtT4xPshr+1GNkyw@mail.gmail.com>
Accept-Language: en-US
Content-Language: en-US
user-agent: Microsoft-MacOutlook/14.3.1.130117
acceptlanguage: en-US
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0

Awesome work Mike!

On 2/19/13 4:38 PM, "Michael Brooks" <michael@michaelbrooks.ca> wrote:

>Update: Short-term goal [1] is now complete.
>
>The documentation is hosted on Apache infrastructure under the Apache
>Cordova website. Additionally, http://docs.cordova.io/ redirects to the
>Apache Cordova documentation.
>
>[1]: https://issues.apache.org/jira/browse/CB-1880
>
>On Thu, Feb 7, 2013 at 4:00 PM, Michael Brooks
><michael@michaelbrooks.ca>wrote:
>
>> Steve Gill and myself sat down on Friday and reviewed the state of the
>> documentation and where we need it to go.
>>
>> The short-term goal is to host the documentation on
>> http://cordova.apache.org/docs and redirect with http://docs.cordova.io
>>
>> The long-term goal is everything else - theming, organization, document
>> structure, etc. I don't want this discussion to happen on this thread.
>>
>> The short-term goal is small and focused. No automation for updating or
>> anything like that. It's meant to achieve our objective on the Apache
>>board
>> report and set a new objective. After hosting the documentation, we will
>> need to cull the versions down to only those that are part of Apache
>> Cordova (removing the old PhoneGap versions). We can look into an
>> auto-update mechanism, although the generator will be replaced in the
>> long-term goal.
>>
>> A downside to hosting the documentation on the website's SVN is that it
>> will shoot up to roughly 600MB (300MB in public/ and 300MB in www/). We
>>can
>> reduce this by removing the irrelevant versions.
>>
>> As Fil mentioned, this week has been busy. Before starting work, I'll
>> create and update the relevant JIRA issues, then open a discussion on
>>where
>> we want the docs to go.
>>
>> Michael
>>
>> On Thu, Feb 7, 2013 at 12:47 PM, Filip Maj <fil@adobe.com> wrote:
>>
>>> Not sure.. Michael's had a busy week and he's had ideas on this one
>>>for a
>>> while. Mike?
>>>
>>> On 2/7/13 10:31 AM, "Marcel Kinard" <cmarcelk@gmail.com> wrote:
>>>
>>> >Poking this thread with the release of 2.4.
>>> >
>>> >Where are we at?
>>> >
>>> >Is there anything I can do to help?
>>> >
>>> >-- Marcel Kinard
>>> >
>>> >On Jan 17, 2013, at 12:19 PM, Michael Brooks
>>><michael@michaelbrooks.ca>
>>> >wrote:
>>> >
>>> >>>
>>> >>> I've got Jenkins running locally, pulling from cordova-docs,
>>>polling
>>> >>>daily,
>>> >>> and generating the docs. But the SVN Publisher doesn't seem to
>>>work:
>>> >>> https://wiki.jenkins-ci.org/display/JENKINS/SVN+Publisher (I tested
>>> it
>>> >>>on
>>> >>> another SVN repo, not Apache's) -- reports success but nothing is
>>> >>>uploaded.
>>> >>> This could be a solution in the interim if I could get the
>>>publisher
>>> to
>>> >>
>>> >>
>>> >> Well, it's an interesting experiment. I don't have the time to look
>>> >>into it
>>> >> now, but
>>> >> as I said I'm working to free up February for the documentation
>>>update.
>>> >> I'll pick
>>> >> your brain about the Jenkins stuff then. Thanks for looking into it.
>>> >>
>>> >> which by the way, the whole tree right now is over
>>> >>> 300MB. en/edge right now is only 7MB
>>> >>
>>> >>
>>> >> That's not a big concern. The rewrite of the documentation will only
>>> >> version the
>>> >> latest. This will make internationalization contributions more
>>> >>confusing,
>>> >> since
>>> >> most update older version of Apache Cordova, but we can solve that
>>> >>with...
>>> >> documentation.
>>> >>
>>> >> On Wed, Jan 16, 2013 at 10:04 AM, Shazron <shazron@gmail.com> wrote:
>>> >>
>>> >>> I've got Jenkins running locally, pulling from cordova-docs,
>>>polling
>>> >>>daily,
>>> >>> and generating the docs. But the SVN Publisher doesn't seem to
>>>work:
>>> >>> https://wiki.jenkins-ci.org/display/JENKINS/SVN+Publisher (I tested
>>> it
>>> >>>on
>>> >>> another SVN repo, not Apache's) -- reports success but nothing is
>>> >>>uploaded.
>>> >>> This could be a solution in the interim if I could get the
>>>publisher
>>> to
>>> >>> actually publish -- which by the way, the whole tree right now is
>>>over
>>> >>> 300MB. en/edge right now is only 7MB.
>>> >>>
>>> >>>
>>> >>> On Mon, Jan 14, 2013 at 9:32 AM, Shazron <shazron@gmail.com> wrote:
>>> >>>
>>> >>>> I agree with Ross that it should be on Apache's servers and not
>>> >>>>somewhere
>>> >>>> else (like Amazon S3). At most some dev could locally install
>>>Jenkins
>>> >>>>and
>>> >>>> run a CI server with a script that can auto update the SVN repo
>>> (using
>>> >>>> their creds), or something - until we can get a permanent solution
>>> >>>>
>>> >>>>
>>> >>>> On Mon, Jan 14, 2013 at 9:22 AM, Michael Brooks <
>>> >>> michael@michaelbrooks.ca>wrote:
>>> >>>>
>>> >>>>> @Andrew I was thinking S3 so that a service can auto-update on
>>>each
>>> >>>>> commit.
>>> >>>>> From Yohei's experience with the cordova.apache.org SVN setup, it
>>> >>>>>looks
>>> >>>>> like automating that is a headache.
>>> >>>>>
>>> >>>>> Michael
>>> >>>>>
>>> >>>>> On Mon, Jan 14, 2013 at 9:16 AM, Andrew Grieve <
>>> agrieve@chromium.org>
>>> >>>>> wrote:
>>> >>>>>
>>> >>>>>> cordova.io is a bunch of redirects. Do you mean to have
>>> >>>>>> docs.cordova.ioredirect to
>>> >>>>>> cordova.apache.org/docs (or something similar)
>>> >>>>>>
>>> >>>>>>
>>> >>>>>> On Mon, Jan 14, 2013 at 12:13 PM, Michael Brooks
>>> >>>>>> <michael@michaelbrooks.ca>wrote:
>>> >>>>>>
>>> >>>>>>> Hi Marcel,
>>> >>>>>>>
>>> >>>>>>> I've got this one my roadmap of tasks.
>>> >>>>>>>
>>> >>>>>>> The short-term goal is to have http://docs.cordova.io host our
>>> >>>>>>> documentation and we'll link to it off http://cordova.io.
>>> >>>>>>>
>>> >>>>>>> The longer-term goal is to have the generator and possibly
>>> >>>>>>>templates
>>> >>>>>>> decoupled from the documentation. At that time, we'll redesign
>>>the
>>> >>>>>>> http://docs.cordova.io to use the http://cordova.io site
>>>design.
>>> >>>>>>>
>>> >>>>>>> My plan is to start this work on February 1st and have it
>>> completed
>>> >>>>> for
>>> >>>>>> the
>>> >>>>>>> next board report.
>>> >>>>>>>
>>> >>>>>>> Michael
>>> >>>>>>>
>>> >>>>>>> On Mon, Jan 14, 2013 at 8:52 AM, Ross Gardler <
>>> >>>>>> rgardler@opendirective.com
>>> >>>>>>>> wrote:
>>> >>>>>>>
>>> >>>>>>>> It not only makes sense I would consider it a priority. Having
>>> the
>>> >>>>> only
>>> >>>>>>>> source of docs on a third party website is a no-go as far as
>>>I'm
>>> >>>>>>> concerned.
>>> >>>>>>>> I raised this issue during incubation and was assured it was a
>>> >>>>>>> transitional
>>> >>>>>>>> thing.
>>> >>>>>>>>
>>> >>>>>>>> Ross
>>> >>>>>>>>
>>> >>>>>>>> Sent from a mobile device, please excuse mistakes and brevity
>>> >>>>>>>> On 14 Jan 2013 08:44, "Marcel Kinard" <cmarcelk@gmail.com>
>>> wrote:
>>> >>>>>>>>
>>> >>>>>>>>> Would it make sense to host a copy of the docs on
>>> >>>>> cordova.apache.org
>>> >>>>>> ?
>>> >>>>>>>>> Other Apache projects have their docs online at their
>>> >>>>> apache.orgsite.
>>> >>>>>>>>>
>>> >>>>>>>>> A couple possibilities:
>>> >>>>>>>>> 1) build the html files and zip them up, so a consumer needs
>>>to
>>> >>>>> only
>>> >>>>>>>>> download and unzip and point their browser at their local
>>> >>> offline
>>> >>>>>> copy.
>>> >>>>>>>>> 2) build the html files and post them unpacked to
>>> >>>>>> cordova.apache.orgso
>>> >>>>>>>>> they can be browsed directly without a zip or src download.
>>> >>>>>>>>>
>>> >>>>>>>>> My initial suggestion is to do both: something like
>>> >>>>> /docs/download to
>>> >>>>>>>> hold
>>> >>>>>>>>> the zip files and /docs/browse to have the tree starting with
>>> >>>>>>> index.html.
>>> >>>>>>>>>
>>> >>>>>>>>> Or would it be better to host it in
>>>www.apache.org/dist/cordova
>>> >>> ?
>>> >>>>>>>>>
>>> >>>>>>>>> I am willing to do the initial setup and load.
>>> >>>>>>>>>
>>> >>>>>>>>> Comments?
>>> >>>>>>>>>
>>> >>>>>>>>> -- Marcel Kinard
>>> >>>>>>>>>
>>> >>>>>>>>
>>> >>>>>>>
>>> >>>>>>
>>> >>>>>
>>> >>>>
>>> >>>>
>>> >>>
>>> >
>>>
>>>
>>