Home → Problems →

Homebrew docs don't match local output

• Edit

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

   

   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.

   • Edit

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

   

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

   • Edit

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

   

   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]>>

   • Edit

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

   

   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.

   • Edit

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

   

   Reopening...

   • Edit

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

    

    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?

    • Edit

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

    

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

    • Edit

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

    

    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!

    • Edit

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

    

    All sorted now, thanks!

    • Edit

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