Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
Received-SPF: pass (nike.apache.org: domain of brian.leroux@gmail.com
 designates 209.85.214.175 as permitted sender)
MIME-Version: 1.0
Sender: brian.leroux@gmail.com
In-Reply-To: <CE27BF97.239A1%fil@adobe.com>
References: 
 <CAEeF2TcBhWjaqMUG2eVaWPkBQgE60=nkWhmoqrJbXQdThPLfEw@mail.gmail.com>
	<CE27BF97.239A1%fil@adobe.com>
Date: Wed, 7 Aug 2013 09:35:02 -0700
Message-ID: 
 <CADVgkyNJ_8Vt1AjduGw6xrgQiVAjG6yF1ESpV73Y7LjEEhzncg@mail.gmail.com>
Subject: Re: Cordova Docs in a 3.0 World
From: Brian LeRoux <b@brian.io>
To: dev@cordova.apache.org
Content-Type: text/plain; charset=ISO-8859-1

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