Reduce Build Times?

Question

Reduce Build Times?

jimfoltz opened this issue 8 years ago · 18 comments

Is there a way to speed-up the build of the documentation set? On my system it is taking about 2-1/2 minutes for yard to complete the task. Does the entire database need rebuilt if only one file has been changed?

Answer 1 · 2017-01-14T15:06:55.000Z

The majority of that time appears to be step named:
serializing to doc/file.README.html

(Using --debug option to yard)

Answer 2 · 2017-01-14T18:06:09.000Z

I'm not sure - this would be a question for Yard itself. I'm not sure if you can regen just one file. Would be nice though.

Answer 3 · 2017-01-15T12:53:23.000Z

Work-around:
tim yard --debug && echo ^g

tim is a short Ruby script that times the execution of commands and echo ^g is ctrl-g which dings a bell on the command line.

Answer 4 · 2017-01-15T17:14:35.000Z

Where do you obtain tim?

Answer 5 · 2017-01-15T17:49:24.000Z

heh.

# tim.rb
cmd = ARGV.join(' ')
puts "Timing `#{cmd}...`"
time0 = Time.now
system(cmd)
puts "\ntime: #{Time.now - time0}"

Answer 6 · 2017-01-15T18:47:20.000Z

That's interesting. Wondering what cause it to spend so much time there.

When I run your timing script on the stubs repo I get about 61s. And that generated html file from the readme got an unexpected iframe element.

Answer 7 · 2017-01-15T18:48:48.000Z

If I nuke the README it spends time on [debug]: Serializing to doc/_index.html instead. Suspecting that is building the class/method overview.

Took about the same time; 62s.

Answer 8 · 2017-01-16T08:55:49.000Z

yard server --reload is supposed to only regenerate changed files on-the-fly. It helps but is slow also and the output isn't exactly the same what is generateed by just running yard

Answer 9 · 2017-01-17T09:52:50.000Z

@thomthom

@jimfoltz: Is there a way to speed-up the build of the documentation set?

You can ignore certain files via opts:

--exclude README

One of the first things I did 2 years ago, was to copy and paste the output of yardoc --help into a text file.

yardoc_help.txt

http://www.rubydoc.info/gems/yard/file/README.md

If you want to re-generate your docs with another template you can simply use the
--use-cache (or -c) option to speed up the generation process by skipping source parsing.

More related:

http://www.rubydoc.info/gems/yard/YARD/CLI/Yardoc

Processed Data Storage (.yardoc directory)

When Yardoc parses a source directory, it creates a .yardoc directory (by default, override with -b) at the root of the project. This directory contains marshal dumps for all raw object data in the source, so that you can access it later for various commands (stats, graph, etc.). This directory is also used as a cache for any future calls to yardoc so as to process only the files which have changed since the last call.

When Yardoc uses the cache in subsequent calls to yardoc, methods or classes that have been deleted from source since the last parsing will not be erased from the cache (YARD never deletes objects). In such a case, you should wipe the cache and do a clean parsing of the source tree. You can do this by deleting the .yardoc directory manually, or running Yardoc without --use-cache (-c).

Answer 10 · 2017-01-17T10:59:00.000Z

Oh thanks Dan these sound promising. I'll definitely look into them this afternoon.

Answer 11 · 2017-01-20T01:12:04.000Z

--exclude README won't work apparently; lsegal/yard#837

I looked at the source for YARD, the README is hard coded. :/

Answer 12 · 2017-01-20T17:08:17.000Z

From yardoc --help:

-r, --readme, --main FILE        The readme file used as the title page
                                       of documentation.

So what happens is you specify something other than README ?

... trying it right now ...

I copied ABOUT.md to README.md and README (in the root folder),
then I edited the "yardopts" file to add:
--readme pages/ReleaseNotes.md

...
SUCCESS! When I open the local index now, It opens to the ReleaseNotes !
... and the Files index does not contain a link to the README.

Answer 13 · 2017-01-20T17:33:30.000Z

Yes, you can specify a different README file, but you cannot tell it ignore the README file and continue using the Class index as the index page.

Answer 14 · 2017-01-20T19:06:51.000Z

Trying another go with "yardopts" set to:
--readme NOTHING

My command output looks like:

(uru 2.3 is the first call)
---> Now using ruby 2.3.3-p222 tagged as `2.3-x64`
(pause)
Press any key to continue . . .
(yardoc is called with custom db and output paths)
[warn]: Could not find readme file: NOTHING

... then it just uses the README as the Index.

I find it kinda stupid that this is hardcoded.

Answer 15 · 2017-01-20T21:12:22.000Z

Yea, that issue thread in the YARD repo has a convo where more people are not too happy about this hard-coding.

Answer 16 · 2017-01-20T22:16:30.000Z

... and continue using the Class index as the index page.

FYI, I find that Class Index page worthless. Always have to scroll down. Much faster to use the left nav list.

Answer 17 · 2019-08-31T08:51:10.000Z

Closing this issue as it's a YARD issue.

Answer 18 · 2019-08-31T18:47:50.000Z

And I think the main question was solved with the cache parameter.