Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
Received-SPF: pass (nike.apache.org: domain of agrieve@google.com designates
 209.85.192.178 as permitted sender)
MIME-Version: 1.0
Sender: agrieve@google.com
In-Reply-To: 
 <CAP7NMPoWtrx5KcQsS7Sfxu9tVPxXm0C-y2iv0FyVQkJkZ146zA@mail.gmail.com>
References: 
 <CAEeF2TcBhWjaqMUG2eVaWPkBQgE60=nkWhmoqrJbXQdThPLfEw@mail.gmail.com>
 <CE27BF97.239A1%fil@adobe.com>
 <CADVgkyNJ_8Vt1AjduGw6xrgQiVAjG6yF1ESpV73Y7LjEEhzncg@mail.gmail.com>
 <CAEeF2TeuHu0wC93x8edRrUtLyWrZAi498CCnyeXnLvFEWGuN7A@mail.gmail.com>
 <CAMk5LLndREX-tNuCP_e-7goy9UC5q6py58Lw=s2S=sdaemb5tA@mail.gmail.com>
 <CADVgkyNw_6fXaGbnjgF9iRP_=HRq0y9wXFJ3ovsu=GmkDZSANQ@mail.gmail.com>
 <CAP7NMPoWtrx5KcQsS7Sfxu9tVPxXm0C-y2iv0FyVQkJkZ146zA@mail.gmail.com>
From: Andrew Grieve <agrieve@chromium.org>
Date: Wed, 7 Aug 2013 21:17:53 -0400
Message-ID: 
 <CABiQX1W5vCsvPnUAueM=NYSx=FtvbivTv66xCGB-qpzXCXFJrA@mail.gmail.com>
Subject: Re: Cordova Docs in a 3.0 World
To: dev <dev@cordova.apache.org>
Content-Type: multipart/alternative; boundary=e89a8ffbaca1921be104e3656e1d

--e89a8ffbaca1921be104e3656e1d
Content-Type: text/plain; charset=ISO-8859-1

Sounds great!


On Wed, Aug 7, 2013 at 8:27 PM, Michael Brooks <michael@michaelbrooks.ca>wrote:

> Thanks for kicking this off Andrew.
>
> As Brian mentioned, we've now gone some cycles to work on this problem and
> I'd be happy to lead it forward.
>
> I'll put together a *cringe* wiki article *cringe* summarizing the goals
> forward, but here is the breakdown that I see:
>
> Plugins should bundle their own documentation. As Braden mentioned, we
> should let git deal with the versioning. The directory structure should be:
>     cordova-plugin-name/doc/en/
>
> Platforms should bundle their own documentation. Same format as above.
>
> Cordova Docs repository will be slimmed down only include guides. Same
> format as above.
>
> We will create a node-based tool to pull documentation from multiple
> sources and render the documentation to HTML. This tool can be used
> standalone to generate the documentation that can be published somewhere.
> Additionally, the tool can be used as a module by cordova-cli to generate
> offline documentation from cache libraries and plugins.
>
> Michael
>
>
> On Wed, Aug 7, 2013 at 11:19 AM, Brian LeRoux <b@brian.io> wrote:
>
> > yes, exactly so, and it separates the concern of documenting vs
> > publishing meaning we can experiment w/ the publishing side without
> > getting caught w/ our docs lagging behind
> >
> > On Wed, Aug 7, 2013 at 11:04 AM, Braden Shepherdson <braden@chromium.org
> >
> > wrote:
> > > +1 to that folder structure, especially with the languages. Plugins
> come
> > > with up-to-date documentation; no need to insert separate versions
> here.
> > > Git can handle the versioning better than having separate directories.
> > >
> > > Braden
> > >
> > >
> > > On Wed, Aug 7, 2013 at 10:08 AM, Michal Mocny <mmocny@chromium.org>
> > wrote:
> > >
> > >> I like that folder structure.
> > >>
> > >>
> > >> On Wed, Aug 7, 2013 at 12:35 PM, Brian LeRoux <b@brian.io> wrote:
> > >>
> > >> > Ya, we were just discussing this in Adobe land. The current idea is
> > >> > that a plugin has a ./docs/ folder which contains all the markdown
> and
> > >> > *possibly* a config file.
> > >> >
> > >> > Something like this:
> > >> >
> > >> > ./plugin-whatever
> > >> >  |-docs/
> > >> >  |  |-en/
> > >> >  ...
> > >> >
> > >> > And then we'd have a viewer/transformer code and deal w/ publishing
> > >> > elsewhere.
> > >> >
> > >> >
> > >> > On Wed, Aug 7, 2013 at 9:12 AM, Filip Maj <fil@adobe.com> wrote:
> > >> > > I'd like to see docs and tests moved into the plugin repos
> > eventually,
> > >> > > with us putting work into our tools to support documentation and
> > >> testing
> > >> > > workflows.
> > >> > >
> > >> > > How that all shakes out still has to be determined :)
> > >> > >
> > >> > > Hopefully that will end up encouraging plugin authors to write
> > >> docs/tests
> > >> > > :)
> > >> > >
> > >> > > On 8/7/13 8:44 AM, "Michal Mocny" <mmocny@chromium.org> wrote:
> > >> > >
> > >> > >>+1 to README bundled with the plugin, and having a `cordova docs`,
> > so
> > >> > that
> > >> > >>we can have offline documentation.
> > >> > >>
> > >> > >>I would also like a way to have the guides available offline, but
> > >> perhaps
> > >> > >>that could come in the form of a cordova-plugin-guides or come
> > bundled
> > >> > >>with
> > >> > >>cordova-cli and be included with every 'cordova docs' as part of
> the
> > >> > >>template?
> > >> > >>
> > >> > >>-Michal
> > >> > >>
> > >> > >>
> > >> > >>On Wed, Aug 7, 2013 at 10:51 AM, Andrew Grieve <
> > agrieve@chromium.org>
> > >> > >>wrote:
> > >> > >>
> > >> > >>> If we're releasing plugins independently (which is great!), then
> > it
> > >> > >>>doesn't
> > >> > >>> make sense to have all of our plugin APIs documented as one, and
> > >> under
> > >> > >>>the
> > >> > >>> same parent version.
> > >> > >>>
> > >> > >>> e.g. Right now we have: docs/3.0/File , docs/3.0/InAppBrowser,
> > etc.
> > >> > >>>
> > >> > >>> One option is to switch away from having the version as the
> > parent:
> > >> > >>>
> > >> > >>> docs/File/3.0
> > >> > >>> docs/File/3.1
> > >> > >>> docs/InAppBrowser/3.0
> > >> > >>> ...
> > >> > >>>
> > >> > >>> Or even just fold version changes into the docs:
> > >> > >>>
> > >> > >>> docs/File
> > >> > >>>    "File.moveToTrash (added in 3.1)"
> > >> > >>>
> > >> > >>>
> > >> > >>> Another option is to move the plugin docs into the plugins:
> > >> > >>> cordova-plugin-file/docs
> > >> > >>>
> > >> > >>> It looks like this has somewhat been attempted already, as there
> > are
> > >> > >>>files
> > >> > >>> that exist here:
> > >> > >>>
> > >> > >>> > ~/git/cordova$ ls cordova-plugin-file/docs/
> > >> > >>> > directoryentry/    file.md            fileerror/
> > >> filereader/
> > >> > >>> >    fileuploadoptions/ filewriter/        localfilesystem/
> > >> > >>> > directoryreader/   fileentry/         fileobj/
> > >> filesystem/
> > >> > >>> >  fileuploadresult/  flags/             metadata/
> > >> > >>>
> > >> > >>>
> > >> > >>> but this format doesn't seem very user-friendly, and doesn't
> lend
> > >> > >>>itself to
> > >> > >>> supporting translations.
> > >> > >>>
> > >> > >>> Maybe we could fold all the docs for a plugin into a single
> > README.md
> > >> > >>>file?
> > >> > >>> Other languages could have README-fr.md, README-pl.md, etc, all
> at
> > >> the
> > >> > >>>root
> > >> > >>> of the repo (or under a translations/ subdirectory?)
> > >> > >>>
> > >> > >>> In this scheme guides would stay under cordova-docs, but all of
> > the
> > >> API
> > >> > >>> docs would live in the plugin repos. Perhaps we could have a
> > "cordova
> > >> > >>>docs"
> > >> > >>> command that would convert all of your installed plugins into
> > html,
> > >> > >>>create
> > >> > >>> an index page, and open it in a browser?
> > >> > >>>
> > >> > >>> Any other ideas?
> > >> > >>>
> > >> > >
> > >> >
> > >>
> >
>

--e89a8ffbaca1921be104e3656e1d--