cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Filip Maj <...@adobe.com>
Subject Re: Cordova Docs in a 3.0 World
Date Wed, 07 Aug 2013 16:12:07 GMT
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?
>>


Mime
View raw message