Further fixes for including package information in docs

Further fixes for including package information in docs

Committed: https://code.google.com/p/dart/source/detail?r=29606

[Alan Knight, 2013-10-28 20:37:40]

- Incorporate the package's readme.md file in the docs for the main library in
that package. If you don't have such a library, right now it won't include the
readme.
- Put package documentation in a subdirectory, so we don't have name conflicts
between files from different sources.
- Changes to have a consistent URL structure that doesn't use dots in the name
(library a with top-level field b as "a.b" is ambiguous with library "a.b". So
we always use package/library-replacing-dots-with-dashes.member.submember
and we generate them that way from docgen so the viewer can be simplified.
- store both the simple and qualified name in the index
- get rid of a couple of type warnings

[terry, 2013-10-30 18:11:31]

Few minor suggestions and trying to understand the library name change from . to
-

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/bin/upl...
File pkg/docgen/bin/upload_docgen.py (right):

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/bin/upl...
pkg/docgen/bin/upload_docgen.py:92: Upload('.', GS_SITE + '/' + revision + '/')
Would this work then you wouldn't have to chdir to drill then then back out
again?

Upload(os.getwd() + '/docs', GS_SITE + '/' + revision + '/')

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
File pkg/docgen/lib/docgen.dart (right):

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
pkg/docgen/lib/docgen.dart:155: (each is File &&
each.path.substring(packageDir.length + 1, each.path.length)
> 80

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
pkg/docgen/lib/docgen.dart:159: readmes.sort((a, b) =>
a.length.compareTo(b.length));
Nice using sort.

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
pkg/docgen/lib/docgen.dart:310: if (parseSdk) (entityMap['dart-core.Object'] as
Class).subclasses.clear();
Is there a reason we can't use the name we see in our JSON files
dart.core.Object or is this a recent change that I haven't seen yet with core.

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
pkg/docgen/lib/docgen.dart:748: String toString() => super.toString() + '(' +
name.toString() + ')';
String toString() => '${super.toString()}($name)'

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
pkg/docgen/lib/docgen.dart:772: : packageName + '/';
'$packageName/';

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
pkg/docgen/lib/docgen.dart:1313: /// Given a mirror, returns its qualified name,
but following the conventions
Is this an internal representation that isn't exposed to the user?  A user would
never use import "dart-core:Map" but "dart:Map".

[Alan Knight, 2013-10-30 18:31:33]

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/bin/upl...
File pkg/docgen/bin/upload_docgen.py (right):

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/bin/upl...
pkg/docgen/bin/upload_docgen.py:92: Upload('.', GS_SITE + '/' + revision + '/')
On 2013/10/30 18:11:31, terry wrote:
> Would this work then you wouldn't have to chdir to drill then then back out
> again?
> 
> Upload(os.getwd() + '/docs', GS_SITE + '/' + revision + '/')

That works, but then uploads into a subdirectory called docs in cloud storage,
which is not where the client expects to find them.

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
File pkg/docgen/lib/docgen.dart (right):

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
pkg/docgen/lib/docgen.dart:155: (each is File &&
each.path.substring(packageDir.length + 1, each.path.length)
On 2013/10/30 18:11:31, terry wrote:
> > 80

Done.

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
pkg/docgen/lib/docgen.dart:310: if (parseSdk) (entityMap['dart-core.Object'] as
Class).subclasses.clear();
On 2013/10/30 18:11:31, terry wrote:
> Is there a reason we can't use the name we see in our JSON files
> dart.core.Object or is this a recent change that I haven't seen yet with core.

That is the name in the JSON files now, we're using it consistently everywhere.

Using dots as the separator for members when we can have dots in the library
name is ambiguous. We can't tell the difference between the library a.b and the
library a, top-level field b. The client was already doing lots of
transformations where it added - into the library name for URIs (and colons so
you could write dart:core) so I made it always consistently use dashes in the
library name and do the conversion at generation time.

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
pkg/docgen/lib/docgen.dart:748: String toString() => super.toString() + '(' +
name.toString() + ')';
On 2013/10/30 18:11:31, terry wrote:
> String toString() => '${super.toString()}($name)'

Done.

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
pkg/docgen/lib/docgen.dart:772: : packageName + '/';
On 2013/10/30 18:11:31, terry wrote:
> '$packageName/';

Done.

https://chromiumcodereview.appspot.com/47603014/diff/40001/pkg/docgen/lib/doc...
pkg/docgen/lib/docgen.dart:1313: /// Given a mirror, returns its qualified name,
but following the conventions
On 2013/10/30 18:11:31, terry wrote:
> Is this an internal representation that isn't exposed to the user?  A user
would
> never use import "dart-core:Map" but "dart:Map".

This is what goes into the JSON now, and it's exposed to the user in the sense
that it's what's used in the URLs, which are now always of the form
#package/library-name.class.method#anythingExtraWeNeed

The names will display with normal punctuation. dart:core.Map (although we
normally would just use the simple names)

[Alan Knight, 2013-10-30 23:00:26]

Committed patchset #5 manually as r29606 (presubmit successful).