You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by Andrew Grieve <ag...@chromium.org> on 2013/08/07 16:51:42 UTC
Cordova Docs in a 3.0 World
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?
Re: Cordova Docs in a 3.0 World
Posted by Andrew Grieve <ag...@chromium.org>.
Sounds great!
On Wed, Aug 7, 2013 at 8:27 PM, Michael Brooks <mi...@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 <mm...@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 <fi...@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" <mm...@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?
> > >> > >>>
> > >> > >
> > >> >
> > >>
> >
>
Re: Cordova Docs in a 3.0 World
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
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 <br...@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 <mm...@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 <fi...@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" <mm...@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?
> >> > >>>
> >> > >
> >> >
> >>
>
Re: Cordova Docs in a 3.0 World
Posted by Brian LeRoux <b...@brian.io>.
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 <br...@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 <mm...@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 <fi...@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" <mm...@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 <ag...@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?
>> > >>>
>> > >
>> >
>>
Re: Cordova Docs in a 3.0 World
Posted by Braden Shepherdson <br...@chromium.org>.
+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 <mm...@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 <fi...@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" <mm...@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 <ag...@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?
> > >>>
> > >
> >
>
Re: Cordova Docs in a 3.0 World
Posted by Michal Mocny <mm...@chromium.org>.
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 <fi...@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" <mm...@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 <ag...@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?
> >>>
> >
>
Re: Cordova Docs in a 3.0 World
Posted by Brian LeRoux <b...@brian.io>.
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 <fi...@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" <mm...@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 <ag...@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?
>>>
>
Re: Cordova Docs in a 3.0 World
Posted by Filip Maj <fi...@adobe.com>.
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" <mm...@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 <ag...@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?
>>
Re: Cordova Docs in a 3.0 World
Posted by Michal Mocny <mm...@chromium.org>.
+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 <ag...@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?
>