Autolink declarations

[esad]

This solves #483 - autolinking return and argument types in the method declarations in both Swift and Objective-C.

I've reused the same autolinking logic already used for text, with an additional flag that instead of running it inside <code>, runs it inside rogue (syntax highlighting) emitted <span> tags of special classes.

The diff for the integration specs will be quite huge as this affects lots of generated html - so it would be a good idea if you someone can take a look at what this does to their own docs - the output for both Realm ObjC and Swift looks good (and has nice links in the return and argument types!)

[esad]

Ok perhaps this could be rewritten to be consisent with the above doc.return = autolink(..) if doc.return style?

[esad]

If I refactor this to doc.declaration = .. if doc.declaration the line gets too long and rubocop complains :( Should I refactor anyway and disable the rubocop warning?

[jpsim]

Woohoo! This is nice. Could you please address @segiddins's style feedback, push the changes to the integration specs (you should have commit access now 🎉) and then we'll be able to take a look at the specs diff and look at the changes in a web browser.

Thanks!

[jpsim]

@esad now that I've made a few fixes to jazzy and generally brought it back to good health (or at least I hope), could you please revive this so we can include it in the next release?

[esad]

@jpsim Almost there. Rubocop is complaining about a few things, so I wanted to ask for advice how to best deal with it:

lib/jazzy/sourcekitten.rb:440:71: C: Method has too many lines. [24/20]
lib/jazzy/sourcekitten.rb:440:71: C: Perceived complexity for autolink_text is too high. [8/7]
lib/jazzy/sourcekitten.rb:480:70: C: Line is too long. [98/80]
        doc.declaration = autolink_text(doc.declaration, doc, root_decls, true) if doc.declaration

Not sure if I can split the autolink_text method meaningfully to avoid complexity and too many lines errors. Can I just disable Rubocop here?

Regarding the line length offence for doc.declaration - should we switch all three invocations to use &&= syntax?

[jpsim]

This is a great start @esad! There are a few behaviors that I think should be addressed before getting this in:

First, disabling auto-linking to the same page you're already on:

This is a screenshot taken from building the integration specs with this branch, and includes links from Alamofire's Manager to Manager.

Second, disabling links to types not defined in the module:

This is another screenshot taken from building the integration specs with this branch, and includes links from Alamofire's SessionDelegate to NSURLRequest because Alamofire contains extensions to NSURLRequest.

Those are the only two issues I can identify with this for now. Another modification we could consider is preserving the syntax color of the type from rouge, distinguishing between hyperlinks and non-links some other way, like underlines... I'm not too picky if we do this or not.

[jpsim]

As for the rubocop violations, do whatever you prefer there.

[DangerCI]

      <tr>
    <td>:white_check_mark:</td>
    <td data-sticky="true"><del><p>Please include a CHANGELOG entry. 

You can find it at CHANGELOG.md.

	1 Error </th> </tr>
🚫	Please include a CHANGELOG entry. You can find it at CHANGELOG.md.
✅	Please include a CHANGELOG entry. You can find it at CHANGELOG.md.
✅	Please include a CHANGELOG entry. You can find it at CHANGELOG.md.
✅	Please include a CHANGELOG entry. You can find it at CHANGELOG.md.
✅	Please include a CHANGELOG entry. You can find it at CHANGELOG.md.
✅	Please include a CHANGELOG entry. You can find it at CHANGELOG.md.

      <tr>
    <td>:white_check_mark:</td>
    <td data-sticky="true"><del>This PR may need tests.</del></td>
  </tr>

	:white_check_mark: Yay. </th> </tr>

	1 Message </th> </tr>
📖	Note, we hard-wrap at 80 chars and use 2 spaces after the last line.

Generated by 🚫 danger

[esad]

@jpsim

I've addressed the two things you mentioned above, updated the integration specs and tweaked rubocop rules a bit. Travis is failing because of missing CHANGELOG entry, I was think that you may want to craft that one?

The fact that we don't autolink on the same page anymore will also affect previous autolinking logic, where this was not respected, so for example in the abstract for https://realm.io/docs/objc/latest/api/Classes/RLMRealm.html#/c:objc(cs)RLMRealm(cm)defaultRealm, the RLMRealm won't be autolinked.

I've also updated the logic not to perform autolinking to extensions (such as NSURLRequest).

I had some issues with integration specs for MiscJazzyFeatures having extra *.md files residing in a Docs/ subdirectory where also the autogenerated docs go per default, so I moved those to Extra/*.md.

As for Rubocop, I've tried to disable as little checks as possible and comply with the style, but I had to disable complexity checks for the autolinking method, however I think it's still quite readable. I've also globally disabled a recently introduced style check for multiline block chaining that IMHO makes no sense (see rubocop/rubocop#2338), which was also causing some old code in sourcekitten.rb to fail the check.

I've also updated the code to autolink declarations from the the "other language declaration", introduced in v0.6.1.

[jpsim]

Hey @esad, there were conflicts since merging #569 so I worked to resolve those and rebuild the integration specs to better review this.

I did this in the jazzy@jp-autolink-decls and specs@jp-autolink-decls branches.

The main issue I can find with this are that some declarations now link to themselves:

[esad]

@jpsim I've merged your changes and extended the check to prevent autolinking to the same page in the cases like the one you mentioned above. Can you have another look?

[jpsim]

I'll review this again today @esad. I have to thank you for your patience, I know it's been tedious to keep this updated 😬

[segiddins]

CI is only failing due to lack of a CHANGELOG entry

[jpsim]

Previously, we'd link to other child declarations on the current page, like properties on class documentation. These no longer autolink. See the startRequestsImmediately reference in Alamofire's docs:

before:

after:

[esad]

@jpsim I thought that's what the intended behavior per your comment in #490 (comment) was - can you clarify in more detail what do you think the behavior should be when it comes to linking to the same page? Link everything except to itself and to the toplevel declaration of the current page (Manager in your example?)

[jpsim]

Sorry for not being clear, yes I agree with your description of the intended behavior:

Link everything except to itself and to the top-level declaration of the current page

[esad]

@jpsim Updated. Could you have one more look?

[jpsim]

Looks good, I've continued this in #588

[esad]

@jpsim Thanks for taking over with the latest merge, looks good.