Permalink
Browse files

Added the 'documentation' field to pub.dartlang.org.

  • Loading branch information...
1 parent be6eb90 commit 5af66c056493a7d4cc9197a133f386c398bc1b98 @amouravski amouravski committed Feb 8, 2013
View
23 app/doc/pubspec.markdown
@@ -7,6 +7,7 @@ title: "Pubspec Format"
1. [Description](#description)
1. [Author/Authors](#authorauthors)
1. [Homepage](#homepage)
+1. [Documentation](#documentation)
1. [Dependencies](#dependencies)
1. [Dependency sources](#dependency-sources)
1. [Hosted packages](#hosted-packages)
@@ -34,6 +35,8 @@ At the top level are a series of fields. The currently supported ones are:
<dd>Optional.</dd>
<dt>Homepage</dt>
<dd>Optional.</dd>
+ <dt>Documentation</dt>
+ <dd>Optional.</dd>
<dt>Dependencies</dt>
<dd>Can be omitted if your package has no dependencies.</dd>
</dl>
@@ -50,6 +53,7 @@ description: >
functionality you've been looking for.
author: Nathan Weizenbaum <nweiz@google.com>
homepage: http://newtify.dartlang.org
+documentation: http://newtify.dartlang.org/docs
dependencies:
efts: '>=2.0.4 <3.0.0'
transmogrify: '>=0.4.0'
@@ -132,6 +136,25 @@ can always use the URL where you host the source code:
[GitHub](http://github.com), [code.google.com](http://code.google.com/),
whatever.
+## Documentation
+
+This should be a URL pointing to the documentation for your package. For
+[hosted packages](#hosted-packages), this URL will be linked from the
+package's page. Although optional, you are strongly encouraged to create
+documentation for your package so that users can understand how your package
+works, and what libraries, classes and methods you provide. You may choose to
+link to an article, tutorial, documentation hub, or to the documentation
+generated from your source code.
+
+You can generate documentation from your source code with the
+`dartdoc` utility found in the Dart SDK and packaged with the Dart Editor.
@nex3
nex3 Feb 8, 2013

Giving a sample invocation of dartdoc that works for the standard package structure might be nice.

+Documentation generated will resemble
+[Dart's own API documentation](http://api.dartlang.org).
+The [Dart Doc Comments Guidelines](http://www.dartlang.org/articles/doc-comment-guidelines/)
@nex3
nex3 Feb 8, 2013

"Comments" -> "Comment"

+explains how dartdoc comments are structured.
+You might use [GitHub Pages](http://pages.github.com), which provides free web
@nex3
nex3 Feb 8, 2013

This is a little confusing, since you were just talking about generating docs rather than hosting them. I think most people also know about GitHub; this mention is probably unnecessary.

+hosting for projects.
+
## Dependencies
Finally, the pubspec's *raison d'être*:
View
6 app/models/package.py
@@ -60,6 +60,12 @@ def homepage(self):
return self.latest_version.pubspec.get('homepage')
@property
+ def documentation(self):
+ """The documentation URL for the package, or None."""
+ if self.latest_version is None: return None
+ return self.latest_version.pubspec.get('documentation')
+
+ @property
def authors_title(self):
"""The title for the authors list of the package."""
return 'Author' if len(self.latest_version.pubspec.authors) == 1 \
View
12 app/models/pubspec.py
@@ -10,10 +10,10 @@
class Pubspec(dict):
"""A parsed pubspec.yaml file."""
- _STRING_FIELDS = ['name', 'version', 'author', 'homepage']
+ _STRING_FIELDS = ['name', 'version', 'author', 'homepage', 'documentation']
"""Pubspec fields that must be strings if they're defined at all."""
- _HOMEPAGE_SCHEME_RE = re.compile(r'^https?:')
+ _URL_SCHEME_RE = re.compile(r'^https?:')
def __init__(self, *args, **kwargs):
super(Pubspec, self).__init__(*args, **kwargs)
@@ -34,12 +34,18 @@ def __init__(self, *args, **kwargs):
'Pubspec field "authors" must be a string or list, was "%r"' %
self['authors'])
- if 'homepage' in self and not Pubspec._HOMEPAGE_SCHEME_RE.match(
+ if 'homepage' in self and not Pubspec._URL_SCHEME_RE.match(
self['homepage']):
raise db.BadValueError(
'Pubspec field "homepage" can only use "http" or "https" ' +
'schemes.')
+ if 'documentation' in self and not Pubspec._URL_SCHEME_RE.match(
+ self['documentation']):
+ raise db.BadValueError(
+ 'Pubspec field "documentation" can only use "http" or ' +
+ '"https" schemes.')
+
@classmethod
def from_archive(cls, tar):
"""Extract and return the parsed pubspec from a package archive.
View
6 app/views/doc/index.html
@@ -182,7 +182,7 @@ <h2 id="importing-code-from-a-dependency">Importing code from a dependency</h2>
it. To access a library in a another package, you will import it using the
<code>package:</code> scheme:</p>
-<div class="highlight"><pre><code class="dart"><span class="n">import</span> <span class="s1">&#39;package:transmogrify/transmogrify.dart&#39;</span><span class="p">;</span>
+<div class="highlight"><pre><code class="dart"><span class="k">import</span> <span class="s1">&#39;package:transmogrify/transmogrify.dart&#39;</span><span class="p">;</span>
@nex3
nex3 Feb 8, 2013

It looks like you may have a different version of pygments installed than Bob and I; I can't think why else it would change the span class here. I've got 1.5 installed.

</code></pre>
</div>
@@ -211,15 +211,15 @@ <h2 id="importing-code-from-a-dependency">Importing code from a dependency</h2>
<p>The <code>parser_test</code> file <em>could</em> import <code>parser.dart</code> like this:</p>
-<div class="highlight"><pre><code class="dart"><span class="n">import</span> <span class="s1">&#39;../../lib/parser.dart&#39;</span><span class="p">;</span>
+<div class="highlight"><pre><code class="dart"><span class="k">import</span> <span class="s1">&#39;../../lib/parser.dart&#39;</span><span class="p">;</span>
</code></pre>
</div>
<p>But that&rsquo;s a pretty nasty relative path. If <code>parser_test.dart</code> is ever moved
up or down a directory, that path will break and you&rsquo;ll have to fix the code.
Instead, you can do:</p>
-<div class="highlight"><pre><code class="dart"><span class="n">import</span> <span class="s1">&#39;package:transmogrify/parser.dart&#39;</span><span class="p">;</span>
+<div class="highlight"><pre><code class="dart"><span class="k">import</span> <span class="s1">&#39;package:transmogrify/parser.dart&#39;</span><span class="p">;</span>
</code></pre>
</div>
View
10 app/views/doc/package-layout.html
@@ -113,7 +113,7 @@ <h2 id="readme">README</h2>
package. This is the perfect place to introduce people to your code.</p>
<p>If your README ends in <code>.md</code>, <code>.markdown</code>, or <code>.mdown</code>, it will be parsed as
-<a href="http://daringfireball.net/projects/markdown/">Markdown</a> so you can make it as fancy nicely formatted as you like.</p>
+<a href="http://daringfireball.net/projects/markdown/">Markdown</a> so you can make it as fancy as you like.</p>
<h2 id="public-libraries">Public libraries</h2>
@@ -135,8 +135,8 @@ <h2 id="public-libraries">Public libraries</h2>
<p>When you do, users can import these libraries using the name of the package and
the library file, like so:</p>
-<div class="highlight"><pre><code class="dart"><span class="n">import</span> <span class="s2">&quot;package:enchilada/enchilada.dart&quot;</span><span class="p">;</span>
-<span class="n">import</span> <span class="s2">&quot;package:enchilada/tortilla.dart&quot;</span><span class="p">;</span>
+<div class="highlight"><pre><code class="dart"><span class="k">import</span> <span class="s2">&quot;package:enchilada/enchilada.dart&quot;</span><span class="p">;</span>
+<span class="k">import</span> <span class="s2">&quot;package:enchilada/tortilla.dart&quot;</span><span class="p">;</span>
</code></pre>
</div>
@@ -153,7 +153,7 @@ <h2 id="public-libraries">Public libraries</h2>
<p>Users will import <code>olives.dart</code> like:</p>
-<div class="highlight"><pre><code class="dart"><span class="n">import</span> <span class="s2">&quot;package:enchilada/some/path/olives.dart&quot;</span><span class="p">;</span>
+<div class="highlight"><pre><code class="dart"><span class="k">import</span> <span class="s2">&quot;package:enchilada/some/path/olives.dart&quot;</span><span class="p">;</span>
</code></pre>
</div>
@@ -188,7 +188,7 @@ <h2 id="implementation-files">Implementation files</h2>
can (and should) still use <code>"package:"</code> to import them. This is perfectly
legit:</p>
-<div class="highlight"><pre><code class="dart"><span class="n">import</span> <span class="s2">&quot;package:enchilada/src/beans.dart&quot;</span><span class="p">;</span>
+<div class="highlight"><pre><code class="dart"><span class="k">import</span> <span class="s2">&quot;package:enchilada/src/beans.dart&quot;</span><span class="p">;</span>
</code></pre>
</div>
View
2 app/views/doc/pub-install.html
@@ -13,7 +13,7 @@
<p>Once the dependencies are installed, they may be referenced in Dart code. For
example, if a package depends on <code>unittest</code>:</p>
-<div class="highlight"><pre><code class="dart"><span class="n">import</span> <span class="s2">&quot;package:unittest/unittest.dart;</span>
+<div class="highlight"><pre><code class="dart"><span class="k">import</span> <span class="s2">&quot;package:unittest/unittest.dart;</span>
</code></pre>
</div>
View
23 app/views/doc/pubspec.html
@@ -4,6 +4,7 @@
<li><a href="#description">Description</a></li>
<li><a href="#authorauthors">Author/Authors</a></li>
<li><a href="#homepage">Homepage</a></li>
+ <li><a href="#documentation">Documentation</a></li>
<li><a href="#dependencies">Dependencies</a></li>
<li><a href="#dependency-sources">Dependency sources</a>
<ol>
@@ -34,6 +35,8 @@
<dd>Optional.</dd>
<dt>Homepage</dt>
<dd>Optional.</dd>
+ <dt>Documentation</dt>
+ <dd>Optional.</dd>
<dt>Dependencies</dt>
<dd>Can be omitted if your package has no dependencies.</dd>
</dl>
@@ -49,6 +52,7 @@
<span class="no">functionality you&#39;ve been looking for.</span>
<span class="l-Scalar-Plain">author</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Nathan Weizenbaum &lt;nweiz@google.com&gt;</span>
<span class="l-Scalar-Plain">homepage</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">http://newtify.dartlang.org</span>
+<span class="l-Scalar-Plain">documentation</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">http://newtify.dartlang.org/docs</span>
<span class="l-Scalar-Plain">dependencies</span><span class="p-Indicator">:</span>
<span class="l-Scalar-Plain">efts</span><span class="p-Indicator">:</span> <span class="s">&#39;&gt;=2.0.4</span><span class="nv"> </span><span class="s">&lt;3.0.0&#39;</span>
<span class="l-Scalar-Plain">transmogrify</span><span class="p-Indicator">:</span> <span class="s">&#39;&gt;=0.4.0&#39;</span>
@@ -130,6 +134,25 @@ <h2 id="homepage">Homepage</h2>
<a href="http://github.com">GitHub</a>, <a href="http://code.google.com/">code.google.com</a>,
whatever.</p>
+<h2 id="documentation">Documentation</h2>
+
+<p>This should be a URL pointing to the documentation for your package. For
+<a href="#hosted-packages">hosted packages</a>, this URL will be linked from the
+package&rsquo;s page. Although optional, you are strongly encouraged to create
+documentation for your package so that users can understand how your package
+works, and what libraries, classes and methods you provide. You may choose to
+link to an article, tutorial, documentation hub, or to the documentation
+generated from your source code.</p>
+
+<p>You can generate documentation from your source code with the
+<code>dartdoc</code> utility found in the Dart SDK and packaged with the Dart Editor.
+Documentation generated will resemble
+<a href="http://api.dartlang.org">Dart&rsquo;s own API documentation</a>.
+The <a href="http://www.dartlang.org/articles/doc-comment-guidelines/">Dart Doc Comments Guidelines</a>
+explains how dartdoc comments are structured.
+You might use <a href="http://pages.github.com">GitHub Pages</a>, which provides free web
+hosting for projects.</p>
+
<h2 id="dependencies">Dependencies</h2>
<p>Finally, the pubspec&rsquo;s <em>raison d&rsquo;être</em>:
View
5 app/views/packages/show.mustache
@@ -110,6 +110,11 @@ $ <strong>pub install</strong>
<p><a href="{{package.homepage}}">{{package.homepage}}</a></p>
{{/package.homepage}}
+ {{#package.documentation}}
+ <h4>Documentation</h4>
+ <p><a href="{{package.documentation}}">{{package.documentation}}</a></p>
+ {{/package.documentation}}
+
<h4>{{package.uploaders_title}}</h4>
<p>{{& package.uploaders_html}}</p>
</div>
View
17 test/test_models/test_pubspec.py
@@ -58,5 +58,22 @@ def test_requires_homepage_to_use_http_or_https(self):
self.assert_invalid_pubspec(homepage="data:image/png;base64,somedata")
self.assert_invalid_pubspec(homepage="no-scheme.com")
+ def test_requires_documentation_to_be_string(self):
+ self.assert_invalid_pubspec(documentation=12)
+
+ def test_requires_documentation_to_use_http_or_https(self):
+ self.assertEqual(
+ Pubspec(documentation="http://dartlang.org")["documentation"],
+ "http://dartlang.org")
+ self.assertEqual(
+ Pubspec(documentation="https://dartlang.org")["documentation"],
+ "https://dartlang.org")
+
+ self.assert_invalid_pubspec(documentation="ftp://badscheme.com")
+ self.assert_invalid_pubspec(documentation="javascript:alert('!!!')")
+ self.assert_invalid_pubspec(
+ documentation="data:image/png;base64,somedata")
+ self.assert_invalid_pubspec(documentation="no-scheme.com")
+
def assert_invalid_pubspec(self, **kwargs):
self.assertRaises(db.BadValueError, lambda: Pubspec(**kwargs))

0 comments on commit 5af66c0

Please sign in to comment.