Dartdoc on Dart 2 massively slower than Dart 1 #1943
Comments
|
Is this related to #1827 ? |
|
Thanks for the report!
I suspect unrelated, and it may not be related to the dart 1 / dart 2 changeover. We're now verifying more aspects of the generated code, so the slowdown is likely due to performing additional work. That said, 30x slower does sounds larger than expected. |
|
Thanks for investigating @devoncarew .. any other details I can provide to help pin things down? |
|
@devoncarew We're getting closer to having all of our packages switched over to dart2 at which point we'll have to move docs generation from dart 1 to 2. We'd like to avoid the large increase in generation times when that happens, so any help here would be appreciated. I also tried the |
|
Would this be related to having to build a fully resolved AST for all dependencies? |
|
I would also be interested to know if |
|
Any update on this? Finding that running dartdoc takes 27 min on a fairly small package because of ~/.pub-cache, so we are opting not to run it at all. Thanks! |
|
@devoncarew @jcollins-g would it be possible to get any sort of update on this? Is dartdoc supposed to run on all dependencies by default? And if so, is there a way to only generate docs for the current package? I thought based on the name that I also tried adding a dartdoc:
include:
- w_transportBut that only sped up generation by a few seconds. It would be helpful to know whether this slowdown is just the expected result given the amount of additional work dartdoc is doing now compared to on dart 1, or if this is unexpected. When packages are published to pub, what command is run to generate those docs? Is it just |
|
It is an expected result; dartdoc attempts to compute a lot more, including support for external hyperlinks and hyperlinking packages together, and public interface canonicalization. This means dartdoc currently checks all dependent packages to determine where a specific element needs to be documented. It's complicated, because depending on flags Dartdoc might document an inherited or reexported element in many different places. It shouldn't be as slow as it is, though -- there is a lot of room for improvement. |
|
the question of how dartdoc is run on the pub site is complicated, but here is the main entry point: https://github.com/dart-lang/pub-dev/blob/1148c9180efe14e05d2be09da5697848bee0af40/pkg/pub_dartdoc/bin/pub_dartdoc.dart |
|
FYI, --no-auto-include-dependencies is the default. Dartdoc still needs to read many dependencies even if it doesn't generate docs on them. Here are some flags you can try to reduce generation time if you're in a CI or other environment where performance is important:
|
|
I've reduced the time to generate docs, for dartdoc 0.32.3, but not by 32x. :/ |
|
Is there anything actionable here? I agree we should be faster...and maybe set some SLO about speed. But I'm not sure how we act on this issue. |
|
I don't think there is anything actionable here; I especially don't think we can set a goal to be "as fast as Dart 1 was" (hard to measure, arbitrary). I like the idea of setting an SLO to generate the flutter docs. Currently I think they take ~13 minutes still on an MBP. I'd love to get that down below 10 minutes. @jcollins-g also has plans for improving dartdoc reference resolution which removes the magical global references, and might dramatically speed up dartdoc generation. Not sure if those plans are tracked here... |
srawlins
added
the
type-bug
|
As a new user to Dart, I found it surprising and somewhat concerning when I discovered that running a simple Given that doc generators for pretty much any other language / toolchain that I've used (Python, Go, Rust, Java, etc.) take seconds if not milliseconds to run on much larger projects, this seems prohibitively slow. Is there any ongoing investigation or work being done to try and improve this situation? This was the only relevant issue I could find in your Github project. |
|
For reference, I did read the comment thread here, and if I try some of the workarounds suggested throughout - many of which require the use of the |
We are actively working on removing the "universal reference scope" feature, via converting some code to use "doc imports." You can track dart-lang/sdk#50702. I don't think there is a local issue to track removing "universal reference scope." But that should improve performance. Beyond that, there are no plans to investigate performance. You can also look at the 'type-performance' label on the issue tracker: https://github.com/dart-lang/dartdoc/issues?q=is%3Aopen+is%3Aissue+label%3Atype-performance |
|
Another interesting test case that I did, I tried using the To be clear, this is a complete no-op operation because I've asked the tool to generate docs for a non-existent library, and it still takes nearly the same amount of time to complete as a full build operation. :( |
Thanks for the reply. I'll keep an eye on them. |
|
This is probably not the right place for this, but I figured I'd just throw it out there. From a back-end developer point of view, it would be nice even if I could just get the doc strings for my current project exported into a simple markdown or html format, without any cross referencing or cross linking with any external dependencies of any kind, so that I could get fast feedback on the output that is generated (excluding hyperlinks / reference links of course). This would be very helpful for quick feedback when you just want to see if the basic inline formatting you are putting in your doc strings is being parsed correctly. I'm not sure if such a feature already exists, or if it is even possible. But anything that could be done to make doc generation - at least on small to medium size projects - run in seconds / milliseconds instead of minutes would be of tremendous value from a usability perspective. |
|
One other anecdote for comparison purposes: I've been using the Hugo static site generator for some doc generation and blogging stuff, and it can parse a markdown file and generate HTML content from it in something like 2ms. Some people use it to generate sites with thousands or tens of thousands of pages in a matter of seconds. When you have tools like this setting the bar so high, it makes the expectations for other similar tools to be at least in somewhat close proximity. |
|
Another flag that might improve performance (not sure though) is |
|
That doesn't seem to have an appreciable impact: |
Summary
Running dartdoc on a private package, I've noticed it takes 32x as long on dart 2. Under dart 1 it just parses the single library whereas under dart 2 it parses ALL of the packages before it even generates any docs.
15s - dartdoc on dart 1.24.3 (dartdoc version 0.9.14-dev)
8m 17s - dartdoc on dart 2.2.0 (dartdoc version 0.28.1+2)
Dart 1
Dart 2
The text was updated successfully, but these errors were encountered: