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