Sounds great!
On Wed, Aug 7, 2013 at 8:27 PM, Michael Brooks <[email protected]>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 <[email protected]> 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 <[email protected] > > > > 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 <[email protected]> > > wrote: > > > > > >> I like that folder structure. > > >> > > >> > > >> On Wed, Aug 7, 2013 at 12:35 PM, Brian LeRoux <[email protected]> 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 <[email protected]> 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" <[email protected]> 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 < > > [email protected]> > > >> > >>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? > > >> > >>> > > >> > > > > >> > > > >> > > >
