cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michal Mocny <mmo...@chromium.org>
Subject Re: Cordova Docs in a 3.0 World
Date Wed, 07 Aug 2013 17:08:19 GMT
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