BREAKING CHANGE: dartdoc removed, replaced with docgen

[Alan Knight]

What changed?

• The dartdoc snapshot and corresponding sources are no longer in the build. A snapshot of docgen is now available. However, rather than producing static HTML pages it produces JSON files which are consumed by the dartdoc-viewer polymer app, which is hosted on github. The api.dartlang.org site is now using this mechanism, so the changes can be seen there.

Who is affected?

• Projects that used dartdoc to generate documentation for their own packages, or otherwise relied on dartdoc.

How do I update my code?

• The new mechanism is very different from the previous one. You would need to set up the dartdoc viewer to be served from your site, generate the docgen files and have them served. To experiment with the mechanism you can try docgen --serve. Note that this is a dynamic application, so search engine indexing of docs may be affected.

Why did this change happen?

• Dartdoc was very badly out of date and the new version adds numerous features, including much better ability to document packages.
  

When will the change take effect?

• Dartdoc started to be removed in r32387

[Alan Knight]

On Tue, Feb 11, 2014 at 2:50 PM, Arron Washington <l33...@gmail.com> wrote:

Why did something as basic as code documentation just become so complicated?

Ignoring the major annoyance of no search results when you type in "$dart-package $classname", why isn't the Dart polymer app packaged docgen and setup to consume the new JSON format on a build?

Can you give an example of what you mean by no search results? e.g. if I type "barback asset" into the search box I get results. Or are you talking about google search indexing?

What are you looking for in terms of packaged. Do you mean something like docgen --serve? Or is it something else?

 

--
For more news and information, visit http://news.dartlang.org/
 
To join the conversation, visit https://groups.google.com/a/dartlang.org/

--
For other discussions, see https://groups.google.com/a/dartlang.org/
 
For HOWTO questions, visit http://stackoverflow.com/tags/dart
 
To file a bug report or feature request, go to http://www.dartbug.com/new

To unsubscribe from this group and stop receiving emails from it, send an email to misc+uns...@dartlang.org.

[Alan Knight]

On Tue, Feb 11, 2014 at 3:45 PM, Arron Washington <l33...@gmail.com> wrote:

On Tuesday, February 11, 2014 6:32:38 PM UTC-5, Alan Knight wrote:

On Tue, Feb 11, 2014 at 2:50 PM, Arron Washington <l33...@gmail.com> wrote:

Why did something as basic as code documentation just become so complicated?

Ignoring the major annoyance of no search results when you type in "$dart-package $classname", why isn't the Dart polymer app packaged docgen and setup to consume the new JSON format on a build?

Can you give an example of what you mean by no search results? e.g. if I type "barback asset" into the search box I get results. Or are you talking about google search indexing?

I mean Google / general search engine indexing. When I'm looking for a more broad overview of a class in Ruby (or a gems), or a NodeJS API or an NPM package, generally anything I want is literally a Google search away: "Ruby StringIO", or "nodejs path.extname" (taken from my search history). My search engine knowledge is probably very out of date -- are polymer, angularjs / etc style sites indexed by Google and Co properly now?

They might. We have our fingers crossed. If not, there's a fallback mechanism to point it at static equivalents.

What are you looking for in terms of packaged. Do you mean something like docgen --serve? Or is it something else?

 

For local development at least, when I'm checking to make sure that my dartdoc tags and what have you are rendered correctly, I just want to be able to:

1) compile code documentation

2) open file locally, navigate to section, make sure documentation is formatted correctly / easy to read

3) repeat 1 and reload the page whenever I make a change.

Does docgen --serve enable this? I read the announcement to mean that it served up the JSON file, not a combination of viewer and JSON.

Yes, that's exactly what it's for.

[Emily Fortuna]

If you run dartdoc --help you'll get explanation what the arguments mean. You can see additional documentation here: https://www.dartlang.org/tools/docgen/

On Wed, Mar 19, 2014 at 8:11 AM, Günter Zöchbauer <gzo...@gmail.com> wrote:

I find this documentation somewhat unfortunate:

Deploy docs

To deploy your documentation to the web, do the following:

• Host dartdoc-viewer on your server, compiled to JavaScript.
• Host the generated files, which must be in a directory named docs under the main URL.

How would I do this? Maybe this is what --compile does, but it is not documented.

On Wednesday, March 19, 2014 3:58:17 PM UTC+1, Peter StJ wrote:

Correct me if I am wrong but this new mode means that there is no way to generate simple html files that can be hosted anywhere (like for example github.io) and thus if I am to publish and support several packages I have no option but to write the docs manually and then upload them to wherever I want for my users to reference them if needed? If true, I don't understand how was this decision taken. I just want to publish on github and host the docs on github as well, is this possible now?

--
For more news and information, visit http://news.dartlang.org/
 
To join the conversation, visit https://groups.google.com/a/dartlang.org/