Re: Deleting Plugin Docs
I've left them there: http://cordova.apache.org/docs/en/edge/cordova_plugins_pluginapis.md.html#Plugin%20APIs On Mon, Dec 23, 2013 at 1:33 PM, Wargo, John wrote: > And what happen to features that aren't part of a plugin? Like the > deviceready event, button events, application events for example? Those get > lost if we do plugin-centric docs, right? > > John M. Wargo > Twitter: @johnwargo > > -Original Message- > From: Carlos Santana [mailto:csantan...@gmail.com] > Sent: Friday, December 20, 2013 11:39 AM > To: dev@cordova.apache.org > Subject: Re: Deleting Plugin Docs > > I'm a bit lost > > Is the eventual goal to build the docs as a single website ( > docs.cordova.io) > with multiple repos cordova-docs repo and plugin repos? > > > > On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John wrote: > > > Andrew, > > > > Will you be processing the plugin docs so they generate the pages like > > they used to? Being able to click and link around within a particular > > plugin's doc is super helpful. > > > > John M. Wargo > > Twitter: @johnwargo > > > > > > -Original Message- > > From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew > > Grieve > > Sent: Wednesday, December 18, 2013 10:40 PM > > To: dev > > Subject: Fwd: Deleting Plugin Docs > > > > This is now done! Woo! No more having plugins code separate from their > docs > > (I hear we might even get tests to live within plugin repos in the next > > while too!). > > > > I tried to be diligent, but it's possible I made mistakes along the way. > > You can see the result on the edge version of the docs: > > http://cordova.apache.org/docs/en/edge/ > > > > There's a new "Plugins API" page, and all of the plugin docs are moved > into > > the respective repos within a doc/index.md file. > > > > Some of doc/index.md files are fairly large, and to help with that I > > attempted to remove some of the repetition that I found: Quick Examples > vs. > > Full Examples, Overviews vs Descriptions (in cases where they were saying > > the same thing). > > > > Also - for the file API, I just wrote to refer to the FileSystem spec for > > the API and copied over only the Cordova platform quirks. This will be a > > bad offline experience, so I'm not 100% convinced that was the right > thing > > to do, but wow is that file big if you were to copy over all of the > > documentation! > > > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md > > > > > > -- > Carlos Santana > >
RE: Deleting Plugin Docs
Nope those remain. The baseline impl just basically webview+those events. On Dec 24, 2013 4:41 AM, "Wargo, John" wrote: > And what happen to features that aren't part of a plugin? Like the > deviceready event, button events, application events for example? Those get > lost if we do plugin-centric docs, right? > > John M. Wargo > Twitter: @johnwargo > > -Original Message- > From: Carlos Santana [mailto:csantan...@gmail.com] > Sent: Friday, December 20, 2013 11:39 AM > To: dev@cordova.apache.org > Subject: Re: Deleting Plugin Docs > > I'm a bit lost > > Is the eventual goal to build the docs as a single website ( > docs.cordova.io) > with multiple repos cordova-docs repo and plugin repos? > > > > On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John wrote: > > > Andrew, > > > > Will you be processing the plugin docs so they generate the pages like > > they used to? Being able to click and link around within a particular > > plugin's doc is super helpful. > > > > John M. Wargo > > Twitter: @johnwargo > > > > > > -Original Message- > > From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew > > Grieve > > Sent: Wednesday, December 18, 2013 10:40 PM > > To: dev > > Subject: Fwd: Deleting Plugin Docs > > > > This is now done! Woo! No more having plugins code separate from their > docs > > (I hear we might even get tests to live within plugin repos in the next > > while too!). > > > > I tried to be diligent, but it's possible I made mistakes along the way. > > You can see the result on the edge version of the docs: > > http://cordova.apache.org/docs/en/edge/ > > > > There's a new "Plugins API" page, and all of the plugin docs are moved > into > > the respective repos within a doc/index.md file. > > > > Some of doc/index.md files are fairly large, and to help with that I > > attempted to remove some of the repetition that I found: Quick Examples > vs. > > Full Examples, Overviews vs Descriptions (in cases where they were saying > > the same thing). > > > > Also - for the file API, I just wrote to refer to the FileSystem spec for > > the API and copied over only the Cordova platform quirks. This will be a > > bad offline experience, so I'm not 100% convinced that was the right > thing > > to do, but wow is that file big if you were to copy over all of the > > documentation! > > > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md > > > > > > -- > Carlos Santana > >
RE: Deleting Plugin Docs
And what happen to features that aren't part of a plugin? Like the deviceready event, button events, application events for example? Those get lost if we do plugin-centric docs, right? John M. Wargo Twitter: @johnwargo -Original Message- From: Carlos Santana [mailto:csantan...@gmail.com] Sent: Friday, December 20, 2013 11:39 AM To: dev@cordova.apache.org Subject: Re: Deleting Plugin Docs I'm a bit lost Is the eventual goal to build the docs as a single website (docs.cordova.io) with multiple repos cordova-docs repo and plugin repos? On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John wrote: > Andrew, > > Will you be processing the plugin docs so they generate the pages like > they used to? Being able to click and link around within a particular > plugin's doc is super helpful. > > John M. Wargo > Twitter: @johnwargo > > > -Original Message- > From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew > Grieve > Sent: Wednesday, December 18, 2013 10:40 PM > To: dev > Subject: Fwd: Deleting Plugin Docs > > This is now done! Woo! No more having plugins code separate from their docs > (I hear we might even get tests to live within plugin repos in the next > while too!). > > I tried to be diligent, but it's possible I made mistakes along the way. > You can see the result on the edge version of the docs: > http://cordova.apache.org/docs/en/edge/ > > There's a new "Plugins API" page, and all of the plugin docs are moved into > the respective repos within a doc/index.md file. > > Some of doc/index.md files are fairly large, and to help with that I > attempted to remove some of the repetition that I found: Quick Examples vs. > Full Examples, Overviews vs Descriptions (in cases where they were saying > the same thing). > > Also - for the file API, I just wrote to refer to the FileSystem spec for > the API and copied over only the Cordova platform quirks. This will be a > bad offline experience, so I'm not 100% convinced that was the right thing > to do, but wow is that file big if you were to copy over all of the > documentation! > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md > -- Carlos Santana
Re: Deleting Plugin Docs
> > The problem I saw with the full examples, is that they are copy & pastes of > the "Quick Examples", but put within an html page and an onDeviceReady > callback. Given that the default app templates already have this, is it > really necessary to have it in every example? You can still copy & paste > without having to replace your entire file. That said, maybe once we have > our own plugins.cordova.io docs rendering engine, we could have examples > auto-expand into full page examples via a button? Yea, as Andrew concluded long file examples can always be hidden with a little CSS to expand and contract. In the long-run, I would like to see "Full Examples" live outside of the documentation in the directory: /plugin-name/example//index.html The documentation website can fetch these examples to display, but users can also run the examples whenever a plugin in downloaded, cloned, or installed. I think this adds more value to the Full Examples and makes them easier to maintain since they are runnable beyond copy & paste. Forgot to mentioned consistency look and feel (i.e. CSS) between the > *three*primary websites ! > www.cordova.io > docs.cordova.io > plugins.cordova.io In the long-run, I'd like to see http://plugins.cordova.io host the plugin documentation. It should have a rich navigation that supports multiple doc file and multiple versions. This allows ALL plugins to have rich documentation generated from .md files - not just the official APIs. By making documentation simple, we should be able to encourage users to write docs for their own plugins. As Carlos mentioned, the looks & feel of docs.cordova.io and docs on plugins.cordova.io should be a seamless design experience. Rad discussion guys! Michael On Fri, Dec 20, 2013 at 11:16 AM, Brian LeRoux wrote: > Yes! > On Dec 21, 2013 2:50 AM, "Andrew Grieve" wrote: > > > The eventual goal (in my eyes) is to have plugin docs: > > 1. Appear with the plugins on plugins.cordova.io. > > 2. Be accessible to devs after they have installed the plugin (e.g. by > > looking at plugins/foo/doc, or maybe by having "cordova serve" show them) > > > > > > > > > > On Fri, Dec 20, 2013 at 11:38 AM, Carlos Santana > >wrote: > > > > > I'm a bit lost > > > > > > Is the eventual goal to build the docs as a single website ( > > > docs.cordova.io) > > > with multiple repos cordova-docs repo and plugin repos? > > > > > > > > > > > > On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John > > wrote: > > > > > > > Andrew, > > > > > > > > Will you be processing the plugin docs so they generate the pages > like > > > > they used to? Being able to click and link around within a > particular > > > > plugin's doc is super helpful. > > > > > > > > John M. Wargo > > > > Twitter: @johnwargo > > > > > > > > > > > > -Original Message- > > > > From: agri...@google.com [mailto:agri...@google.com] On Behalf Of > > Andrew > > > > Grieve > > > > Sent: Wednesday, December 18, 2013 10:40 PM > > > > To: dev > > > > Subject: Fwd: Deleting Plugin Docs > > > > > > > > This is now done! Woo! No more having plugins code separate from > their > > > docs > > > > (I hear we might even get tests to live within plugin repos in the > next > > > > while too!). > > > > > > > > I tried to be diligent, but it's possible I made mistakes along the > > way. > > > > You can see the result on the edge version of the docs: > > > > http://cordova.apache.org/docs/en/edge/ > > > > > > > > There's a new "Plugins API" page, and all of the plugin docs are > moved > > > into > > > > the respective repos within a doc/index.md file. > > > > > > > > Some of doc/index.md files are fairly large, and to help with that I > > > > attempted to remove some of the repetition that I found: Quick > Examples > > > vs. > > > > Full Examples, Overviews vs Descriptions (in cases where they were > > saying > > > > the same thing). > > > > > > > > Also - for the file API, I just wrote to refer to the FileSystem spec > > for > > > > the API and copied over only the Cordova platform quirks. This will > be > > a > > > > bad offline experience, so I'm not 100% convinced that was the right > > > thing > > > > to do, but wow is that file big if you were to copy over all of the > > > > documentation! > > > > > > > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md > > > > > > > > > > > > > > > > -- > > > Carlos Santana > > > > > > > > >
Re: Deleting Plugin Docs
Yes! On Dec 21, 2013 2:50 AM, "Andrew Grieve" wrote: > The eventual goal (in my eyes) is to have plugin docs: > 1. Appear with the plugins on plugins.cordova.io. > 2. Be accessible to devs after they have installed the plugin (e.g. by > looking at plugins/foo/doc, or maybe by having "cordova serve" show them) > > > > > On Fri, Dec 20, 2013 at 11:38 AM, Carlos Santana >wrote: > > > I'm a bit lost > > > > Is the eventual goal to build the docs as a single website ( > > docs.cordova.io) > > with multiple repos cordova-docs repo and plugin repos? > > > > > > > > On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John > wrote: > > > > > Andrew, > > > > > > Will you be processing the plugin docs so they generate the pages like > > > they used to? Being able to click and link around within a particular > > > plugin's doc is super helpful. > > > > > > John M. Wargo > > > Twitter: @johnwargo > > > > > > > > > -Original Message- > > > From: agri...@google.com [mailto:agri...@google.com] On Behalf Of > Andrew > > > Grieve > > > Sent: Wednesday, December 18, 2013 10:40 PM > > > To: dev > > > Subject: Fwd: Deleting Plugin Docs > > > > > > This is now done! Woo! No more having plugins code separate from their > > docs > > > (I hear we might even get tests to live within plugin repos in the next > > > while too!). > > > > > > I tried to be diligent, but it's possible I made mistakes along the > way. > > > You can see the result on the edge version of the docs: > > > http://cordova.apache.org/docs/en/edge/ > > > > > > There's a new "Plugins API" page, and all of the plugin docs are moved > > into > > > the respective repos within a doc/index.md file. > > > > > > Some of doc/index.md files are fairly large, and to help with that I > > > attempted to remove some of the repetition that I found: Quick Examples > > vs. > > > Full Examples, Overviews vs Descriptions (in cases where they were > saying > > > the same thing). > > > > > > Also - for the file API, I just wrote to refer to the FileSystem spec > for > > > the API and copied over only the Cordova platform quirks. This will be > a > > > bad offline experience, so I'm not 100% convinced that was the right > > thing > > > to do, but wow is that file big if you were to copy over all of the > > > documentation! > > > > > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md > > > > > > > > > > > -- > > Carlos Santana > > > > >
Re: Deleting Plugin Docs
Agreed, that is a goal. Mike is looking at Docs, Joni/Steve/Anis Plugins, and we can refresh WWW last. On Dec 21, 2013 3:05 AM, "Carlos Santana" wrote: > Forgot to mentioned consistency look and feel (i.e. CSS) between the > *three*primary websites ! > > www.cordova.io > docs.cordova.io > plugins.cordova.io > > > > On Fri, Dec 20, 2013 at 11:52 AM, Carlos Santana >wrote: > > > All docs for Cordova CLI, Plugman CLI, and Platforms hosted/rendered on > > docs.cordova.io > > and > > All docs for Plugins hosted/rendered on plugins.cordova.io > > > > If this is true, I would like to see consistencies on look and feel of > > both websites, and ability to link back and forth between sites via > links. > > > > > > > > > > On Fri, Dec 20, 2013 at 11:42 AM, Andrew Grieve >wrote: > > > >> The eventual goal (in my eyes) is to have plugin docs: > >> 1. Appear with the plugins on plugins.cordova.io. > >> 2. Be accessible to devs after they have installed the plugin (e.g. by > >> looking at plugins/foo/doc, or maybe by having "cordova serve" show > them) > >> > >> > >> > >> > >> On Fri, Dec 20, 2013 at 11:38 AM, Carlos Santana >> >wrote: > >> > >> > I'm a bit lost > >> > > >> > Is the eventual goal to build the docs as a single website ( > >> > docs.cordova.io) > >> > with multiple repos cordova-docs repo and plugin repos? > >> > > >> > > >> > > >> > On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John > >> wrote: > >> > > >> > > Andrew, > >> > > > >> > > Will you be processing the plugin docs so they generate the pages > like > >> > > they used to? Being able to click and link around within a > particular > >> > > plugin's doc is super helpful. > >> > > > >> > > John M. Wargo > >> > > Twitter: @johnwargo > >> > > > >> > > > >> > > -Original Message- > >> > > From: agri...@google.com [mailto:agri...@google.com] On Behalf Of > >> Andrew > >> > > Grieve > >> > > Sent: Wednesday, December 18, 2013 10:40 PM > >> > > To: dev > >> > > Subject: Fwd: Deleting Plugin Docs > >> > > > >> > > This is now done! Woo! No more having plugins code separate from > their > >> > docs > >> > > (I hear we might even get tests to live within plugin repos in the > >> next > >> > > while too!). > >> > > > >> > > I tried to be diligent, but it's possible I made mistakes along the > >> way. > >> > > You can see the result on the edge version of the docs: > >> > > http://cordova.apache.org/docs/en/edge/ > >> > > > >> > > There's a new "Plugins API" page, and all of the plugin docs are > moved > >> > into > >> > > the respective repos within a doc/index.md file. > >> > > > >> > > Some of doc/index.md files are fairly large, and to help with that > I > >> > > attempted to remove some of the repetition that I found: Quick > >> Examples > >> > vs. > >> > > Full Examples, Overviews vs Descriptions (in cases where they were > >> saying > >> > > the same thing). > >> > > > >> > > Also - for the file API, I just wrote to refer to the FileSystem > spec > >> for > >> > > the API and copied over only the Cordova platform quirks. This will > >> be a > >> > > bad offline experience, so I'm not 100% convinced that was the right > >> > thing > >> > > to do, but wow is that file big if you were to copy over all of the > >> > > documentation! > >> > > > >> > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md > >> > > > >> > > >> > > >> > > >> > -- > >> > Carlos Santana > >> > > >> > > >> > > > > > > > > -- > > Carlos Santana > > > > > > > > -- > Carlos Santana > >
Re: Deleting Plugin Docs
Forgot to mentioned consistency look and feel (i.e. CSS) between the *three*primary websites ! www.cordova.io docs.cordova.io plugins.cordova.io On Fri, Dec 20, 2013 at 11:52 AM, Carlos Santana wrote: > All docs for Cordova CLI, Plugman CLI, and Platforms hosted/rendered on > docs.cordova.io > and > All docs for Plugins hosted/rendered on plugins.cordova.io > > If this is true, I would like to see consistencies on look and feel of > both websites, and ability to link back and forth between sites via links. > > > > > On Fri, Dec 20, 2013 at 11:42 AM, Andrew Grieve wrote: > >> The eventual goal (in my eyes) is to have plugin docs: >> 1. Appear with the plugins on plugins.cordova.io. >> 2. Be accessible to devs after they have installed the plugin (e.g. by >> looking at plugins/foo/doc, or maybe by having "cordova serve" show them) >> >> >> >> >> On Fri, Dec 20, 2013 at 11:38 AM, Carlos Santana > >wrote: >> >> > I'm a bit lost >> > >> > Is the eventual goal to build the docs as a single website ( >> > docs.cordova.io) >> > with multiple repos cordova-docs repo and plugin repos? >> > >> > >> > >> > On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John >> wrote: >> > >> > > Andrew, >> > > >> > > Will you be processing the plugin docs so they generate the pages like >> > > they used to? Being able to click and link around within a particular >> > > plugin's doc is super helpful. >> > > >> > > John M. Wargo >> > > Twitter: @johnwargo >> > > >> > > >> > > -Original Message- >> > > From: agri...@google.com [mailto:agri...@google.com] On Behalf Of >> Andrew >> > > Grieve >> > > Sent: Wednesday, December 18, 2013 10:40 PM >> > > To: dev >> > > Subject: Fwd: Deleting Plugin Docs >> > > >> > > This is now done! Woo! No more having plugins code separate from their >> > docs >> > > (I hear we might even get tests to live within plugin repos in the >> next >> > > while too!). >> > > >> > > I tried to be diligent, but it's possible I made mistakes along the >> way. >> > > You can see the result on the edge version of the docs: >> > > http://cordova.apache.org/docs/en/edge/ >> > > >> > > There's a new "Plugins API" page, and all of the plugin docs are moved >> > into >> > > the respective repos within a doc/index.md file. >> > > >> > > Some of doc/index.md files are fairly large, and to help with that I >> > > attempted to remove some of the repetition that I found: Quick >> Examples >> > vs. >> > > Full Examples, Overviews vs Descriptions (in cases where they were >> saying >> > > the same thing). >> > > >> > > Also - for the file API, I just wrote to refer to the FileSystem spec >> for >> > > the API and copied over only the Cordova platform quirks. This will >> be a >> > > bad offline experience, so I'm not 100% convinced that was the right >> > thing >> > > to do, but wow is that file big if you were to copy over all of the >> > > documentation! >> > > >> > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md >> > > >> > >> > >> > >> > -- >> > Carlos Santana >> > >> > >> > > > > -- > Carlos Santana > > -- Carlos Santana
Re: Deleting Plugin Docs
All docs for Cordova CLI, Plugman CLI, and Platforms hosted/rendered on docs.cordova.io and All docs for Plugins hosted/rendered on plugins.cordova.io If this is true, I would like to see consistencies on look and feel of both websites, and ability to link back and forth between sites via links. On Fri, Dec 20, 2013 at 11:42 AM, Andrew Grieve wrote: > The eventual goal (in my eyes) is to have plugin docs: > 1. Appear with the plugins on plugins.cordova.io. > 2. Be accessible to devs after they have installed the plugin (e.g. by > looking at plugins/foo/doc, or maybe by having "cordova serve" show them) > > > > > On Fri, Dec 20, 2013 at 11:38 AM, Carlos Santana >wrote: > > > I'm a bit lost > > > > Is the eventual goal to build the docs as a single website ( > > docs.cordova.io) > > with multiple repos cordova-docs repo and plugin repos? > > > > > > > > On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John > wrote: > > > > > Andrew, > > > > > > Will you be processing the plugin docs so they generate the pages like > > > they used to? Being able to click and link around within a particular > > > plugin's doc is super helpful. > > > > > > John M. Wargo > > > Twitter: @johnwargo > > > > > > > > > -Original Message- > > > From: agri...@google.com [mailto:agri...@google.com] On Behalf Of > Andrew > > > Grieve > > > Sent: Wednesday, December 18, 2013 10:40 PM > > > To: dev > > > Subject: Fwd: Deleting Plugin Docs > > > > > > This is now done! Woo! No more having plugins code separate from their > > docs > > > (I hear we might even get tests to live within plugin repos in the next > > > while too!). > > > > > > I tried to be diligent, but it's possible I made mistakes along the > way. > > > You can see the result on the edge version of the docs: > > > http://cordova.apache.org/docs/en/edge/ > > > > > > There's a new "Plugins API" page, and all of the plugin docs are moved > > into > > > the respective repos within a doc/index.md file. > > > > > > Some of doc/index.md files are fairly large, and to help with that I > > > attempted to remove some of the repetition that I found: Quick Examples > > vs. > > > Full Examples, Overviews vs Descriptions (in cases where they were > saying > > > the same thing). > > > > > > Also - for the file API, I just wrote to refer to the FileSystem spec > for > > > the API and copied over only the Cordova platform quirks. This will be > a > > > bad offline experience, so I'm not 100% convinced that was the right > > thing > > > to do, but wow is that file big if you were to copy over all of the > > > documentation! > > > > > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md > > > > > > > > > > > -- > > Carlos Santana > > > > > -- Carlos Santana
Re: Deleting Plugin Docs
The eventual goal (in my eyes) is to have plugin docs: 1. Appear with the plugins on plugins.cordova.io. 2. Be accessible to devs after they have installed the plugin (e.g. by looking at plugins/foo/doc, or maybe by having "cordova serve" show them) On Fri, Dec 20, 2013 at 11:38 AM, Carlos Santana wrote: > I'm a bit lost > > Is the eventual goal to build the docs as a single website ( > docs.cordova.io) > with multiple repos cordova-docs repo and plugin repos? > > > > On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John wrote: > > > Andrew, > > > > Will you be processing the plugin docs so they generate the pages like > > they used to? Being able to click and link around within a particular > > plugin's doc is super helpful. > > > > John M. Wargo > > Twitter: @johnwargo > > > > > > -Original Message- > > From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew > > Grieve > > Sent: Wednesday, December 18, 2013 10:40 PM > > To: dev > > Subject: Fwd: Deleting Plugin Docs > > > > This is now done! Woo! No more having plugins code separate from their > docs > > (I hear we might even get tests to live within plugin repos in the next > > while too!). > > > > I tried to be diligent, but it's possible I made mistakes along the way. > > You can see the result on the edge version of the docs: > > http://cordova.apache.org/docs/en/edge/ > > > > There's a new "Plugins API" page, and all of the plugin docs are moved > into > > the respective repos within a doc/index.md file. > > > > Some of doc/index.md files are fairly large, and to help with that I > > attempted to remove some of the repetition that I found: Quick Examples > vs. > > Full Examples, Overviews vs Descriptions (in cases where they were saying > > the same thing). > > > > Also - for the file API, I just wrote to refer to the FileSystem spec for > > the API and copied over only the Cordova platform quirks. This will be a > > bad offline experience, so I'm not 100% convinced that was the right > thing > > to do, but wow is that file big if you were to copy over all of the > > documentation! > > > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md > > > > > > -- > Carlos Santana > >
Re: Deleting Plugin Docs
Not in the short-term. I think our docs should be easy enough to write such that all plugin authors take the time to do it. To me, that means simple .md files. Might be able to do more fancy things when we host on plugins.cordova.io, but for now, it's just github's .md formatting. On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John wrote: > Andrew, > > Will you be processing the plugin docs so they generate the pages like > they used to? Being able to click and link around within a particular > plugin's doc is super helpful. > > John M. Wargo > Twitter: @johnwargo > > > -Original Message- > From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew > Grieve > Sent: Wednesday, December 18, 2013 10:40 PM > To: dev > Subject: Fwd: Deleting Plugin Docs > > This is now done! Woo! No more having plugins code separate from their docs > (I hear we might even get tests to live within plugin repos in the next > while too!). > > I tried to be diligent, but it's possible I made mistakes along the way. > You can see the result on the edge version of the docs: > http://cordova.apache.org/docs/en/edge/ > > There's a new "Plugins API" page, and all of the plugin docs are moved into > the respective repos within a doc/index.md file. > > Some of doc/index.md files are fairly large, and to help with that I > attempted to remove some of the repetition that I found: Quick Examples vs. > Full Examples, Overviews vs Descriptions (in cases where they were saying > the same thing). > > Also - for the file API, I just wrote to refer to the FileSystem spec for > the API and copied over only the Cordova platform quirks. This will be a > bad offline experience, so I'm not 100% convinced that was the right thing > to do, but wow is that file big if you were to copy over all of the > documentation! > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md >
Re: Deleting Plugin Docs
I'm a bit lost Is the eventual goal to build the docs as a single website (docs.cordova.io) with multiple repos cordova-docs repo and plugin repos? On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John wrote: > Andrew, > > Will you be processing the plugin docs so they generate the pages like > they used to? Being able to click and link around within a particular > plugin's doc is super helpful. > > John M. Wargo > Twitter: @johnwargo > > > -Original Message- > From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew > Grieve > Sent: Wednesday, December 18, 2013 10:40 PM > To: dev > Subject: Fwd: Deleting Plugin Docs > > This is now done! Woo! No more having plugins code separate from their docs > (I hear we might even get tests to live within plugin repos in the next > while too!). > > I tried to be diligent, but it's possible I made mistakes along the way. > You can see the result on the edge version of the docs: > http://cordova.apache.org/docs/en/edge/ > > There's a new "Plugins API" page, and all of the plugin docs are moved into > the respective repos within a doc/index.md file. > > Some of doc/index.md files are fairly large, and to help with that I > attempted to remove some of the repetition that I found: Quick Examples vs. > Full Examples, Overviews vs Descriptions (in cases where they were saying > the same thing). > > Also - for the file API, I just wrote to refer to the FileSystem spec for > the API and copied over only the Cordova platform quirks. This will be a > bad offline experience, so I'm not 100% convinced that was the right thing > to do, but wow is that file big if you were to copy over all of the > documentation! > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md > -- Carlos Santana
RE: Deleting Plugin Docs
Andrew, Will you be processing the plugin docs so they generate the pages like they used to? Being able to click and link around within a particular plugin's doc is super helpful. John M. Wargo Twitter: @johnwargo -Original Message- From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew Grieve Sent: Wednesday, December 18, 2013 10:40 PM To: dev Subject: Fwd: Deleting Plugin Docs This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new "Plugins API" page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md
Re: Deleting Plugin Docs
We'll point them to master as soon as the docs exist on master. On Thu, Dec 19, 2013 at 4:13 PM, Marcel Kinard wrote: > +1 to Michael's comments. > > And I know it is a bit too early to do this, but the links to the docs on > github should point to the master branch, not the dev branch, correct? > > I don't think there is anything wrong with big docs, as long as they are > useful and navigable. > >
Re: Deleting Plugin Docs
Thanks! The problem I saw with the full examples, is that they are copy & pastes of the "Quick Examples", but put within an html page and an onDeviceReady callback. Given that the default app templates already have this, is it really necessary to have it in every example? You can still copy & paste without having to replace your entire file. That said, maybe once we have our own plugins.cordova.io docs rendering engine, we could have examples auto-expand into full page examples via a button? Yeah, I now think it would be better to keep the File docs. The immediate problem with multiple files is that there's no way to do a side-nav with them hosted on github as .md files. Maybe we could have one file that just holds all of the examples, and another that's just the API spec? On Thu, Dec 19, 2013 at 4:00 PM, Michael Brooks wrote: > Nice Andrew. > > I think the "Plugins API" page is a good start. We can iterate on it > to improve the experience. > > Personally, I would rather not have cut out the quick examples, full > examples, etc. Some of the most positive feedback for our > documentation is that it's thorough and copy & paste ready. This helps > to get people up and running quickly. Just my two cents. > > I am very hesitant about removing the File API documentation and > linking to external sources. When files become too large - similar to > functions - we use multiple files. In the past, we've found that the > W3C spec or external documentation (e.g. File API used by certain > browsers) is a moving target. How confident are we that the Cordova > File API will be a 100% match to the HTML 5 Rocks documentation? > > Michael > > On Wed, Dec 18, 2013 at 7:39 PM, Andrew Grieve > wrote: > > This is now done! Woo! No more having plugins code separate from their > docs > > (I hear we might even get tests to live within plugin repos in the next > > while too!). > > > > I tried to be diligent, but it's possible I made mistakes along the way. > > You can see the result on the edge version of the docs: > > http://cordova.apache.org/docs/en/edge/ > > > > There's a new "Plugins API" page, and all of the plugin docs are moved > into > > the respective repos within a doc/index.md file. > > > > Some of doc/index.md files are fairly large, and to help with that I > > attempted to remove some of the repetition that I found: Quick Examples > vs. > > Full Examples, Overviews vs Descriptions (in cases where they were saying > > the same thing). > > > > Also - for the file API, I just wrote to refer to the FileSystem spec for > > the API and copied over only the Cordova platform quirks. This will be a > > bad offline experience, so I'm not 100% convinced that was the right > thing > > to do, but wow is that file big if you were to copy over all of the > > documentation! > > > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md >
Re: Deleting Plugin Docs
+1 to Michael's comments. And I know it is a bit too early to do this, but the links to the docs on github should point to the master branch, not the dev branch, correct? I don't think there is anything wrong with big docs, as long as they are useful and navigable.
Re: Deleting Plugin Docs
Nice Andrew. I think the "Plugins API" page is a good start. We can iterate on it to improve the experience. Personally, I would rather not have cut out the quick examples, full examples, etc. Some of the most positive feedback for our documentation is that it's thorough and copy & paste ready. This helps to get people up and running quickly. Just my two cents. I am very hesitant about removing the File API documentation and linking to external sources. When files become too large - similar to functions - we use multiple files. In the past, we've found that the W3C spec or external documentation (e.g. File API used by certain browsers) is a moving target. How confident are we that the Cordova File API will be a 100% match to the HTML 5 Rocks documentation? Michael On Wed, Dec 18, 2013 at 7:39 PM, Andrew Grieve wrote: > This is now done! Woo! No more having plugins code separate from their docs > (I hear we might even get tests to live within plugin repos in the next > while too!). > > I tried to be diligent, but it's possible I made mistakes along the way. > You can see the result on the edge version of the docs: > http://cordova.apache.org/docs/en/edge/ > > There's a new "Plugins API" page, and all of the plugin docs are moved into > the respective repos within a doc/index.md file. > > Some of doc/index.md files are fairly large, and to help with that I > attempted to remove some of the repetition that I found: Quick Examples vs. > Full Examples, Overviews vs Descriptions (in cases where they were saying > the same thing). > > Also - for the file API, I just wrote to refer to the FileSystem spec for > the API and copied over only the Cordova platform quirks. This will be a > bad offline experience, so I'm not 100% convinced that was the right thing > to do, but wow is that file big if you were to copy over all of the > documentation! > > https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md
Fwd: Deleting Plugin Docs
This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new "Plugins API" page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md
Re: Deleting Plugin Docs
> Michael - Just to clarify, you're suggesting that we put all docs-related > files *except* the main README.md within "docs/"? This plays well with > github, but wanted to clarify. Maybe translations can one day go in > docs_translated/$LANGUAGE ## project-name/README.md The file should be targeted at contributors. It can describe the project structure, dependencies, issue tracker location, etc. It should refer all users to doc/index.md. ## project-name/doc/index.md The directory should be singular, unless the other root directories are plural (bins, libs, tests, specs, etc). This contains usage information for developers using the project as a binary or library. It can contain multiple files, but there should be an index.md to indicate the starting point. This following the web convention of index.html - if you have the urge to suggest main.md or project-name.md, then please take a moment to reflect on the early web with it's attempt at main.html. Index won. All docs go in the doc/ directory. Translated docs would likewise go under doc/, not docs-translated/. We can decide on whatever convention we wish for with the translated documentation. Either doc// or doc/i8n// would make sense to me. In the case of doc/i8n/ we can make English the default at doc//, which would allow for easy HTML navigation since there would be a meaningful index.html in the root. ## Filename letter case preservation Use a hypen ( - ). Not an underscore ( _ ) and not camel-case (CamelCase). This is the UNIX convention [1] and we are following the Unix convention for all other directory names (bin, lib, src, www, etc). ## Displaying the Docs In the short-term, we can point to the GitHub rendered files. However, that puts us at the whim of Apache's ability to keep GitHub mirroring alive. In the long run, I'd rather see plugins.cordova.io supporting rendering and navigating the content of doc/. [1] http://en.wikipedia.org/wiki/Filename#Letter_case_preservation On Mon, Dec 16, 2013 at 1:22 PM, Andrew Grieve wrote: > Issue created: https://issues.apache.org/jira/browse/CB-5658 > > Brian - no need to align this with plugins.cordova.io release. Until then, > we can point at the github renderings of the READMEs > > Michael - Just to clarify, you're suggesting that we put all docs-related > files *except* the main README.md within "docs/"? This plays well with > github, but wanted to clarify. Maybe translations can one day go in > docs_translated/$LANGUAGE > > Brian - "does raise the query: should plugin install automate config.xml > tags?" Not sure what your asking... > > Marcel - Definitely. > > On Sat, Dec 14, 2013 at 6:59 AM, Marcel Kinard wrote: > >> SGTM. And where the plugin docs are removed from cordova-docs, there >> should be instructions on where consumers can find the relocated plugin >> docs.
Re: Deleting Plugin Docs
Issue created: https://issues.apache.org/jira/browse/CB-5658 Brian - no need to align this with plugins.cordova.io release. Until then, we can point at the github renderings of the READMEs Michael - Just to clarify, you're suggesting that we put all docs-related files *except* the main README.md within "docs/"? This plays well with github, but wanted to clarify. Maybe translations can one day go in docs_translated/$LANGUAGE Brian - "does raise the query: should plugin install automate config.xml tags?" Not sure what your asking... Marcel - Definitely. On Sat, Dec 14, 2013 at 6:59 AM, Marcel Kinard wrote: > SGTM. And where the plugin docs are removed from cordova-docs, there > should be instructions on where consumers can find the relocated plugin > docs.
Re: Deleting Plugin Docs
SGTM. And where the plugin docs are removed from cordova-docs, there should be instructions on where consumers can find the relocated plugin docs.
Re: Deleting Plugin Docs
love the idea. On Dec 13, 2013 3:24 PM, "Shazron" wrote: > +1 from me, makes sense > > > On Fri, Dec 13, 2013 at 2:07 PM, Brian LeRoux wrote: > > > ya I like that plan too > > > > README should just be simple description of what it is and how to install > > > > does raise the query: should plugin install automate config.xml tags? > > > > > > On Sat, Dec 14, 2013 at 8:22 AM, Michael Brooks < > mich...@michaelbrooks.ca > > >wrote: > > > > > Hi Andrew, > > > > > > I like this plan. It aligns perfectly with where I want the docs to go. > > > > > > I would rather see each plugin use a "doc/index.md" file for the API > > > documentation. However, since plugins.cordova.io should auto-generate > > the > > > README.md to HTML, it makes sense to use that file instead. However, I > > > would like to see any assets (images) or additional markdown files > placed > > > in the "doc/" directory. > > > > > > Thanks for taking the lead on this one, > > > Michael > > > > > > > > > On Fri, Dec 13, 2013 at 1:09 PM, Brian LeRoux wrote: > > > > > > > +1 > > > > > > > > (we should time this for the plugins.cordova.io refactor/release so > we > > > > don't have a period of zero published plugin documentation) > > > > > > > > > > > > On Sat, Dec 14, 2013 at 6:47 AM, Andrew Grieve > > > > > wrote: > > > > > > > > > On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny > > > > > wrote: > > > > > > > > > > > RE my last suggest about CLI command for plugin docs, I'm now > > > thinking > > > > it > > > > > > would be better to do something like we plan for tests: ship an > app > > > > that > > > > > > hosts the docs based on whichever plugins you have installed. > > > Perhaps > > > > > the > > > > > > test app should even do both tasks? > > > > > > > > > > > > > > > > I think it'd be fine to think about this as a do-later thing, but I > > > don't > > > > > want to get side-tracked just yet with these kinds of > possibilities. > > > > > > > > > > > > > > > > > > > > > > > > > > > > On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny < > mmo...@chromium.org > > > > > > > > wrote: > > > > > > > > > > > > > Mike, actually I think with this proposal it should be easier > > than > > > > ever > > > > > > to > > > > > > > match plugin to docs specific to its version. > > > > > > > > > > > > > > The documentation would come bundled with the plugin, so you > can > > > find > > > > > the > > > > > > > README.md alongside wherever your plugin code resides, be that > an > > > old > > > > > > > download, a plugman install, or from a git repo locally. > > > > > > > > > > > > > > Andrew, this all sounds pretty good, but looking forward to > > seeing > > > > > > Michael > > > > > > > Brooks/Brian chime in since I think they had a docs plan up > their > > > > > sleeve. > > > > > > > > > > > > > > Also, do we want to add a CLI command to show plugin docs? > > > > > > > > > > > > > > -Michal > > > > > > > > > > > > > > > > > > > > > On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau < > > > mike.bil...@gmail.com > > > > > > >wrote: > > > > > > > > > > > > > >> >> 2. Move plugin information found in cordova-docs into a > > single > > > > > > >> README.md > > > > > > >> file within the respective plugin repos > > > > > > >> And also remove the /cordova/ folder from cordova-docs, right? > > > This > > > > > way > > > > > > >> there will be only one single location for a plugin's > > > documentation > > > > > (the > > > > > > >> README.md file inside that plugin repo). > > > > > > > > > > > Right. The goal is one spot for plugin docs. > > > > > > > > > > > > > > > > >> > > > > > > >> What will we do for docs of older versions? If somebody is > using > > > > 2.9, > > > > > > they > > > > > > >> will need the 2.9 README.md file - is it enough for them to > just > > > > > change > > > > > > >> the > > > > > > >> branch on github? > > > > > > > > > > > This change will not affect publish docs for older versions. for > 2.9, > > > > you'd > > > > > still go to docs.cordova.io's 2.9 documentation. > > > > > > > > > > > > > > > > >> > > > > > > >> Assuming that there is no problem with viewing older > > > documentation, > > > > > then > > > > > > >> +1 > > > > > > >> on all of these. > > > > > > >> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
Re: Deleting Plugin Docs
+1 from me, makes sense On Fri, Dec 13, 2013 at 2:07 PM, Brian LeRoux wrote: > ya I like that plan too > > README should just be simple description of what it is and how to install > > does raise the query: should plugin install automate config.xml tags? > > > On Sat, Dec 14, 2013 at 8:22 AM, Michael Brooks >wrote: > > > Hi Andrew, > > > > I like this plan. It aligns perfectly with where I want the docs to go. > > > > I would rather see each plugin use a "doc/index.md" file for the API > > documentation. However, since plugins.cordova.io should auto-generate > the > > README.md to HTML, it makes sense to use that file instead. However, I > > would like to see any assets (images) or additional markdown files placed > > in the "doc/" directory. > > > > Thanks for taking the lead on this one, > > Michael > > > > > > On Fri, Dec 13, 2013 at 1:09 PM, Brian LeRoux wrote: > > > > > +1 > > > > > > (we should time this for the plugins.cordova.io refactor/release so we > > > don't have a period of zero published plugin documentation) > > > > > > > > > On Sat, Dec 14, 2013 at 6:47 AM, Andrew Grieve > > > wrote: > > > > > > > On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny > > > wrote: > > > > > > > > > RE my last suggest about CLI command for plugin docs, I'm now > > thinking > > > it > > > > > would be better to do something like we plan for tests: ship an app > > > that > > > > > hosts the docs based on whichever plugins you have installed. > > Perhaps > > > > the > > > > > test app should even do both tasks? > > > > > > > > > > > > > I think it'd be fine to think about this as a do-later thing, but I > > don't > > > > want to get side-tracked just yet with these kinds of possibilities. > > > > > > > > > > > > > > > > > > > > > > > On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny > > > > > wrote: > > > > > > > > > > > Mike, actually I think with this proposal it should be easier > than > > > ever > > > > > to > > > > > > match plugin to docs specific to its version. > > > > > > > > > > > > The documentation would come bundled with the plugin, so you can > > find > > > > the > > > > > > README.md alongside wherever your plugin code resides, be that an > > old > > > > > > download, a plugman install, or from a git repo locally. > > > > > > > > > > > > Andrew, this all sounds pretty good, but looking forward to > seeing > > > > > Michael > > > > > > Brooks/Brian chime in since I think they had a docs plan up their > > > > sleeve. > > > > > > > > > > > > Also, do we want to add a CLI command to show plugin docs? > > > > > > > > > > > > -Michal > > > > > > > > > > > > > > > > > > On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau < > > mike.bil...@gmail.com > > > > > >wrote: > > > > > > > > > > > >> >> 2. Move plugin information found in cordova-docs into a > single > > > > > >> README.md > > > > > >> file within the respective plugin repos > > > > > >> And also remove the /cordova/ folder from cordova-docs, right? > > This > > > > way > > > > > >> there will be only one single location for a plugin's > > documentation > > > > (the > > > > > >> README.md file inside that plugin repo). > > > > > > > > > Right. The goal is one spot for plugin docs. > > > > > > > > > > > > > >> > > > > > >> What will we do for docs of older versions? If somebody is using > > > 2.9, > > > > > they > > > > > >> will need the 2.9 README.md file - is it enough for them to just > > > > change > > > > > >> the > > > > > >> branch on github? > > > > > > > > > This change will not affect publish docs for older versions. for 2.9, > > > you'd > > > > still go to docs.cordova.io's 2.9 documentation. > > > > > > > > > > > > > >> > > > > > >> Assuming that there is no problem with viewing older > > documentation, > > > > then > > > > > >> +1 > > > > > >> on all of these. > > > > > >> > > > > > > > > > > > > > > > > > > > > > > > > > > >
Re: Deleting Plugin Docs
ya I like that plan too README should just be simple description of what it is and how to install does raise the query: should plugin install automate config.xml tags? On Sat, Dec 14, 2013 at 8:22 AM, Michael Brooks wrote: > Hi Andrew, > > I like this plan. It aligns perfectly with where I want the docs to go. > > I would rather see each plugin use a "doc/index.md" file for the API > documentation. However, since plugins.cordova.io should auto-generate the > README.md to HTML, it makes sense to use that file instead. However, I > would like to see any assets (images) or additional markdown files placed > in the "doc/" directory. > > Thanks for taking the lead on this one, > Michael > > > On Fri, Dec 13, 2013 at 1:09 PM, Brian LeRoux wrote: > > > +1 > > > > (we should time this for the plugins.cordova.io refactor/release so we > > don't have a period of zero published plugin documentation) > > > > > > On Sat, Dec 14, 2013 at 6:47 AM, Andrew Grieve > > wrote: > > > > > On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny > > wrote: > > > > > > > RE my last suggest about CLI command for plugin docs, I'm now > thinking > > it > > > > would be better to do something like we plan for tests: ship an app > > that > > > > hosts the docs based on whichever plugins you have installed. > Perhaps > > > the > > > > test app should even do both tasks? > > > > > > > > > > I think it'd be fine to think about this as a do-later thing, but I > don't > > > want to get side-tracked just yet with these kinds of possibilities. > > > > > > > > > > > > > > > > > > On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny > > > wrote: > > > > > > > > > Mike, actually I think with this proposal it should be easier than > > ever > > > > to > > > > > match plugin to docs specific to its version. > > > > > > > > > > The documentation would come bundled with the plugin, so you can > find > > > the > > > > > README.md alongside wherever your plugin code resides, be that an > old > > > > > download, a plugman install, or from a git repo locally. > > > > > > > > > > Andrew, this all sounds pretty good, but looking forward to seeing > > > > Michael > > > > > Brooks/Brian chime in since I think they had a docs plan up their > > > sleeve. > > > > > > > > > > Also, do we want to add a CLI command to show plugin docs? > > > > > > > > > > -Michal > > > > > > > > > > > > > > > On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau < > mike.bil...@gmail.com > > > > >wrote: > > > > > > > > > >> >> 2. Move plugin information found in cordova-docs into a single > > > > >> README.md > > > > >> file within the respective plugin repos > > > > >> And also remove the /cordova/ folder from cordova-docs, right? > This > > > way > > > > >> there will be only one single location for a plugin's > documentation > > > (the > > > > >> README.md file inside that plugin repo). > > > > > > > Right. The goal is one spot for plugin docs. > > > > > > > > > > >> > > > > >> What will we do for docs of older versions? If somebody is using > > 2.9, > > > > they > > > > >> will need the 2.9 README.md file - is it enough for them to just > > > change > > > > >> the > > > > >> branch on github? > > > > > > > This change will not affect publish docs for older versions. for 2.9, > > you'd > > > still go to docs.cordova.io's 2.9 documentation. > > > > > > > > > > >> > > > > >> Assuming that there is no problem with viewing older > documentation, > > > then > > > > >> +1 > > > > >> on all of these. > > > > >> > > > > > > > > > > > > > > > > > > > >
Re: Deleting Plugin Docs
Hi Andrew, I like this plan. It aligns perfectly with where I want the docs to go. I would rather see each plugin use a "doc/index.md" file for the API documentation. However, since plugins.cordova.io should auto-generate the README.md to HTML, it makes sense to use that file instead. However, I would like to see any assets (images) or additional markdown files placed in the "doc/" directory. Thanks for taking the lead on this one, Michael On Fri, Dec 13, 2013 at 1:09 PM, Brian LeRoux wrote: > +1 > > (we should time this for the plugins.cordova.io refactor/release so we > don't have a period of zero published plugin documentation) > > > On Sat, Dec 14, 2013 at 6:47 AM, Andrew Grieve > wrote: > > > On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny > wrote: > > > > > RE my last suggest about CLI command for plugin docs, I'm now thinking > it > > > would be better to do something like we plan for tests: ship an app > that > > > hosts the docs based on whichever plugins you have installed. Perhaps > > the > > > test app should even do both tasks? > > > > > > > I think it'd be fine to think about this as a do-later thing, but I don't > > want to get side-tracked just yet with these kinds of possibilities. > > > > > > > > > > > > > On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny > > wrote: > > > > > > > Mike, actually I think with this proposal it should be easier than > ever > > > to > > > > match plugin to docs specific to its version. > > > > > > > > The documentation would come bundled with the plugin, so you can find > > the > > > > README.md alongside wherever your plugin code resides, be that an old > > > > download, a plugman install, or from a git repo locally. > > > > > > > > Andrew, this all sounds pretty good, but looking forward to seeing > > > Michael > > > > Brooks/Brian chime in since I think they had a docs plan up their > > sleeve. > > > > > > > > Also, do we want to add a CLI command to show plugin docs? > > > > > > > > -Michal > > > > > > > > > > > > On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau > > >wrote: > > > > > > > >> >> 2. Move plugin information found in cordova-docs into a single > > > >> README.md > > > >> file within the respective plugin repos > > > >> And also remove the /cordova/ folder from cordova-docs, right? This > > way > > > >> there will be only one single location for a plugin's documentation > > (the > > > >> README.md file inside that plugin repo). > > > > > Right. The goal is one spot for plugin docs. > > > > > > > >> > > > >> What will we do for docs of older versions? If somebody is using > 2.9, > > > they > > > >> will need the 2.9 README.md file - is it enough for them to just > > change > > > >> the > > > >> branch on github? > > > > > This change will not affect publish docs for older versions. for 2.9, > you'd > > still go to docs.cordova.io's 2.9 documentation. > > > > > > > >> > > > >> Assuming that there is no problem with viewing older documentation, > > then > > > >> +1 > > > >> on all of these. > > > >> > > > > > > > > > > > > > >
Re: Deleting Plugin Docs
+1 (we should time this for the plugins.cordova.io refactor/release so we don't have a period of zero published plugin documentation) On Sat, Dec 14, 2013 at 6:47 AM, Andrew Grieve wrote: > On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny wrote: > > > RE my last suggest about CLI command for plugin docs, I'm now thinking it > > would be better to do something like we plan for tests: ship an app that > > hosts the docs based on whichever plugins you have installed. Perhaps > the > > test app should even do both tasks? > > > > I think it'd be fine to think about this as a do-later thing, but I don't > want to get side-tracked just yet with these kinds of possibilities. > > > > > > > > On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny > wrote: > > > > > Mike, actually I think with this proposal it should be easier than ever > > to > > > match plugin to docs specific to its version. > > > > > > The documentation would come bundled with the plugin, so you can find > the > > > README.md alongside wherever your plugin code resides, be that an old > > > download, a plugman install, or from a git repo locally. > > > > > > Andrew, this all sounds pretty good, but looking forward to seeing > > Michael > > > Brooks/Brian chime in since I think they had a docs plan up their > sleeve. > > > > > > Also, do we want to add a CLI command to show plugin docs? > > > > > > -Michal > > > > > > > > > On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau > >wrote: > > > > > >> >> 2. Move plugin information found in cordova-docs into a single > > >> README.md > > >> file within the respective plugin repos > > >> And also remove the /cordova/ folder from cordova-docs, right? This > way > > >> there will be only one single location for a plugin's documentation > (the > > >> README.md file inside that plugin repo). > > > Right. The goal is one spot for plugin docs. > > > > >> > > >> What will we do for docs of older versions? If somebody is using 2.9, > > they > > >> will need the 2.9 README.md file - is it enough for them to just > change > > >> the > > >> branch on github? > > > This change will not affect publish docs for older versions. for 2.9, you'd > still go to docs.cordova.io's 2.9 documentation. > > > > >> > > >> Assuming that there is no problem with viewing older documentation, > then > > >> +1 > > >> on all of these. > > >> > > > > > > > > >
Re: Deleting Plugin Docs
On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny wrote: > RE my last suggest about CLI command for plugin docs, I'm now thinking it > would be better to do something like we plan for tests: ship an app that > hosts the docs based on whichever plugins you have installed. Perhaps the > test app should even do both tasks? > I think it'd be fine to think about this as a do-later thing, but I don't want to get side-tracked just yet with these kinds of possibilities. > > > On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny wrote: > > > Mike, actually I think with this proposal it should be easier than ever > to > > match plugin to docs specific to its version. > > > > The documentation would come bundled with the plugin, so you can find the > > README.md alongside wherever your plugin code resides, be that an old > > download, a plugman install, or from a git repo locally. > > > > Andrew, this all sounds pretty good, but looking forward to seeing > Michael > > Brooks/Brian chime in since I think they had a docs plan up their sleeve. > > > > Also, do we want to add a CLI command to show plugin docs? > > > > -Michal > > > > > > On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau >wrote: > > > >> >> 2. Move plugin information found in cordova-docs into a single > >> README.md > >> file within the respective plugin repos > >> And also remove the /cordova/ folder from cordova-docs, right? This way > >> there will be only one single location for a plugin's documentation (the > >> README.md file inside that plugin repo). > Right. The goal is one spot for plugin docs. > >> > >> What will we do for docs of older versions? If somebody is using 2.9, > they > >> will need the 2.9 README.md file - is it enough for them to just change > >> the > >> branch on github? > This change will not affect publish docs for older versions. for 2.9, you'd still go to docs.cordova.io's 2.9 documentation. > >> > >> Assuming that there is no problem with viewing older documentation, then > >> +1 > >> on all of these. > >> > > > > >
Re: Deleting Plugin Docs
RE my last suggest about CLI command for plugin docs, I'm now thinking it would be better to do something like we plan for tests: ship an app that hosts the docs based on whichever plugins you have installed. Perhaps the test app should even do both tasks? On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny wrote: > Mike, actually I think with this proposal it should be easier than ever to > match plugin to docs specific to its version. > > The documentation would come bundled with the plugin, so you can find the > README.md alongside wherever your plugin code resides, be that an old > download, a plugman install, or from a git repo locally. > > Andrew, this all sounds pretty good, but looking forward to seeing Michael > Brooks/Brian chime in since I think they had a docs plan up their sleeve. > > Also, do we want to add a CLI command to show plugin docs? > > -Michal > > > On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau wrote: > >> >> 2. Move plugin information found in cordova-docs into a single >> README.md >> file within the respective plugin repos >> And also remove the /cordova/ folder from cordova-docs, right? This way >> there will be only one single location for a plugin's documentation (the >> README.md file inside that plugin repo). >> >> What will we do for docs of older versions? If somebody is using 2.9, they >> will need the 2.9 README.md file - is it enough for them to just change >> the >> branch on github? >> >> Assuming that there is no problem with viewing older documentation, then >> +1 >> on all of these. >> > >
Re: Deleting Plugin Docs
Mike, actually I think with this proposal it should be easier than ever to match plugin to docs specific to its version. The documentation would come bundled with the plugin, so you can find the README.md alongside wherever your plugin code resides, be that an old download, a plugman install, or from a git repo locally. Andrew, this all sounds pretty good, but looking forward to seeing Michael Brooks/Brian chime in since I think they had a docs plan up their sleeve. Also, do we want to add a CLI command to show plugin docs? -Michal On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau wrote: > >> 2. Move plugin information found in cordova-docs into a single README.md > file within the respective plugin repos > And also remove the /cordova/ folder from cordova-docs, right? This way > there will be only one single location for a plugin's documentation (the > README.md file inside that plugin repo). > > What will we do for docs of older versions? If somebody is using 2.9, they > will need the 2.9 README.md file - is it enough for them to just change the > branch on github? > > Assuming that there is no problem with viewing older documentation, then +1 > on all of these. >
Re: Deleting Plugin Docs
>> 2. Move plugin information found in cordova-docs into a single README.md file within the respective plugin repos And also remove the /cordova/ folder from cordova-docs, right? This way there will be only one single location for a plugin's documentation (the README.md file inside that plugin repo). What will we do for docs of older versions? If somebody is using 2.9, they will need the 2.9 README.md file - is it enough for them to just change the branch on github? Assuming that there is no problem with viewing older documentation, then +1 on all of these.
Deleting Plugin Docs
I would like to: 1. Delete the docs/ directory from all plugins - They contain stale copies of what's in cordova-docs 2. Move plugin information found in cordova-docs into a single README.md file within the respective plugin repos 3. Delete the "API Reference" section of cordova-docs 4. Add a guide called "Cordova Plugins", which contains: - a link to plugins.cordova.io, - a list of the org.apache.cordova plugins, which link to their README.md files on github - e.g. https://github.com/apache/cordova-plugin-media-capture/blob/master/README.md - These can be changed to point at their plugins.cordova.io page when that shows READMEs. - A link to the 3.3 docs, which still have plugin API reference - Mostly, this is for finding non-english versions. Motivation: - Plugins are on a separate release cycle from platforms & docs. - The documentation is often mismatched due to this - Pull requests for plugins don't update the plugin docs - But I think they would if the docs were in the same repo Caveats: - This will mess up our current translations story for plugins. - I think this can be fixed up though, by changing out http://crowdin.netpush / pull scripts - E.g. have README.md translations go in: cordova-plugin-foo/translations/fr/README.md I'll make a JIRA for this, but want buy-in first.
