cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Brooks <mich...@michaelbrooks.ca>
Subject Re: Cordova Docs in a 3.0 World
Date Thu, 08 Aug 2013 00:27:48 GMT
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?
> >> > >>>
> >> > >
> >> >
> >>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message