cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Grieve <agri...@chromium.org>
Subject Cordova Docs in a 3.0 World
Date Wed, 07 Aug 2013 14:51:42 GMT
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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message