+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? > > >>> > > > > > >
