Homebrew docs don't match local output

Mike McQuaid's Avatar

Mike McQuaid

19 Oct, 2014 11:53 AM

http://www.rubydoc.info/github/Homebrew/homebrew/master/frames

We added a .yardopts file yesterday but it doesn't seem to have had an effect (despite web hook being enabled and a manual update today too).

Any ideas? Thanks for the service!

  1. Support Staff 1 Posted by nap on 19 Oct, 2014 02:34 PM

    nap's Avatar

    There was a stuck cache issue that I addressed this morning (cache invalidation logic). Looks like the docs are updating now. Let me know if that output doesn't look right or if this happens again. I'll be working on overhauling our caching strategy soon, apologies for the inconvenience.

  2. nap closed this discussion on 19 Oct, 2014 02:34 PM.

  3. Mike McQuaid re-opened this discussion on 19 Oct, 2014 02:43 PM

  4. 2 Posted by Mike McQuaid on 19 Oct, 2014 02:43 PM

    Mike McQuaid's Avatar

    Still doesn't look right to me I'm afraid; from the .yardopts file the index should be Library/Homebrew/API.md?

  5. Support Staff 3 Posted by nap on 19 Oct, 2014 02:48 PM

    nap's Avatar

    Okay that’s the feedback I was looking for — I’ll take another look shortly!

    ..nap

    From: Mike McQuaid <[email blocked]>
    Reply: Mike McQuaid <[email blocked]>>

  6. Support Staff 4 Posted by nap on 19 Oct, 2014 04:03 PM

    nap's Avatar

    Rubydoc is warning that it can't find the referenced readme (used with the --main switch):

    [warn]: Could not find readme file: Library/Homebrew/API.md
    

    Try this?

    https://github.com/zapnap/homebrew/blob/master/.yardopts
    

    Let me know if that's not what you're looking for.

  7. nap closed this discussion on 19 Oct, 2014 04:03 PM.

  8. nap re-opened this discussion on 19 Oct, 2014 05:35 PM

  9. Support Staff 5 Posted by nap on 19 Oct, 2014 05:35 PM

    nap's Avatar

    Reopening...

  10. 6 Posted by Mike McQuaid on 19 Oct, 2014 05:44 PM

    Mike McQuaid's Avatar

    Thanks! The doc timestamp looks like it has updated again but things are still the same.

    I've tried to add more stuff to the .yardoc file so it'll be found. Is there any way to reproduce my setup locally that you run there; I'm confused that I didn't see the same error locally.

    Also, not sure if the web hook is working for this repo?

  11. 7 Posted by Mike McQuaid on 19 Oct, 2014 06:20 PM

    Mike McQuaid's Avatar

    Looks like the issue is that the `Library/Homebrew/API.md` is cleaned up so it can't be found at request time.

  12. Support Staff 8 Posted by lsegal on 19 Oct, 2014 08:15 PM

    lsegal's Avatar

    Jumping in here--

    We clean up the repos we checkout to remove all the "source code" after YARD has processed it so we can save on disk space. We end up saving ~80% of the project's size this way, which can be in the order of mb for some projects. This adds up over the tens of thousands of projects we have checked out.

    All that to say-- in order for YARD to detect "extra files" (what we call those readme things), those files need to be specified in the .yardopts. Incidentally that's also how YARD detects extra files.

    The actual YARD format for specifying extra files is yard [opts] SRC_FILES - EXTRA_FILES, noting the "-" separator. Therefore, the .yardopts you actually want to be using is:

    --title "Homebrew"
    --main Library/Homebrew/API.md
    --exclude Library/Homebrew/test/vendor/
    --exclude Library/Homebrew/vendor/
    Library/Homebrew/**/*.rb
    -
    Library/Homebrew/*.md
    *.md
    

    I think the lack of a "-" is what is causing YARD to treat your extra files as source code and then attempt to clean them up.

    This is what it looks like with the "-": http://www.rubydoc.info/github/lsegal/homebrew/master/frames -- you'll also start seeing those files show up in your Files list now too.

    Just submitted a PR for that on your project. Hope that helps!

  13. 9 Posted by Mike McQuaid on 21 Oct, 2014 09:40 PM

    Mike McQuaid's Avatar

    All sorted now, thanks!

  14. nap closed this discussion on 22 Dec, 2014 10:35 PM.

Comments are currently closed for this discussion. You can start a new one.

Keyboard shortcuts

Generic

? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac