[WIP] Custom categories

[pcantrell]

Allows customized logical grouping and ordering of the lefthand doc nav bar.

Type-based groups can make documentation hard to browse. A struct, for example, may have a closely associated protocol (and have nothing to do with another struct that happens to be next to it in alphabetical order).

A new --categories option accepts a YAML or JSON file containing custom categories for the top-level types:

- name: Core
  children:
  - Service
  - Resource
  - ResourceData
  - ResourceError
  - ResourceObserver
  - ResourceEvent
  - Request
  - RequestMethod
  - Configuration

- name: Response Parsing
  children:
  - Response
  - ResponseTransformer
  - ResponseDataTransformer
  - TextTransformer
  - JsonTransformer
  - TransformerSequence

..etc...

Here is what the results look like.

Ordering within each category is preserved. Any types not explicitly categorized show up under “Other Classes,” “Other Protocols,” etc.

On disk, files are still grouped by type (e.g. Classes/Thinger.html), not custom categories. The rationale for this is that changing the categories should not break existing links to docs for individual program elements.

If the --categories option is not present, Jazzy behaves the same as before.

This needs documentation, and probably testing as well, but I’ll wait for feedback from the core team before undertaking that.

[orta]

This is interesting, I can add support for this in the .cocoapods.yml file format we've just started adopting for cocoapods-try for CocoaDocs.

[jpsim]

This is really great! Is there a reason this PR is targeting swift-2.0 rather than master? The more we merge into swift-2.0, the more conflated it gets and the more difficult it will be to merge that in when the time comes.

Otherwise, this looks ready to merge as-is, although some documentation is definitely needed.

I wonder if this feature would be best served by introducing a .jazzy.yml file for jazzy configuration, or if it's sufficient to piggy-pack off existing configuration files that would prevent users from having to add yet another dot file to their repos... I think the custom config file approach is worthwhile, since cocoapods-try (or others) aren't necessarily 100% aligned with the needs of jazzy.

[pcantrell]

It’s on swift-2.0 only because my project is Swift 2.0, so that's what I'm testing it on. FWIW, the swift-2.0 branch seems to be where most of the new dev is happening; it's more ahead master than behind it, if that makes sense.

A .jazzy.yml file makes sense to me. Maybe a --configuration option to specify the file, plus maybe autodetect for .jazzy.yml if the option isn't specified?

[jpsim]

It’s on swift-2.0 only because my project is Swift 2.0, so that's what I'm testing it on. FWIW, the swift-2.0 branch seems to be where most of the new dev is happening; it's more ahead master than behind it, if that makes sense.

I'd like to cut a final release of jazzy targeting Swift 1.2 and then merge swift-2.0 so that we can just start using master as the main development branch.

A .jazzy.yml file makes sense to me. Maybe a --configuration option to specify the file, plus maybe autodetect for .jazzy.yml if the option isn't specified?

That sounds right.

[pcantrell]

Sitting back down to this (at last!), I have some questions about this .jazzy.yml idea.

First, it feels like it should be a separate PR. The only reason not to do it that way is that it would involve adding and then immediately revoking a --categories command line option. Even so, I'm inclined to go ahead and do that, just for the sake of preventing the PR from snowballing. No problem as long as --categories doesn't make it into a release, right? Opinions?

Next question: where should Jazzy look for .jazzy.yml if the --configuration option isn't specified? Plausible options are:

1. Nowhere; you have to specify --configuration and there is no default file.
2. In the current directory.
3. In the same directory as the README.
4. In source_directory.
5. In source_directory or any of its ancestors (a la .git).

Opinions on that one? I tend to like 5, 3, and 1 (in that order) on first instinct, but don't have a clearly formed opinion about it.

[jpsim]

option 4 would be fine, 5 even better

[pcantrell]

Sounds like 5 is the way.

We good with making that a follow-up PR? If so, all we need to merge this one is some docs … right?

[jpsim]

We good with making that a follow-up PR?

Yes, the config file feature should certainly be a separate PR, and a temporary --categories flag is fine by me. I don't think it's necessary to document only to change how it works shortly afterwards.

[pcantrell]

I just fixed the command-line help for that categories so that it's at least correct.

I think this one's ready to merge?

[jpsim]

Running the integration tests on this PR, it's clear there are a few things that still need work. You can see these for yourself by running bundle install; bundle exec rake spec

1. Bad USR warnings used to print A compile error prevented Result.error from receiving a unique USR., but now print A compile error prevented #<Jazzy::SourceDeclaration:0x007fc7c933d068>.error from receiving a unique USR.
2. Nested type declarations have now been "lifted": Classes/Request/TaskDelegate.html -> Classes/TaskDelegate.html for Alamofire

[pcantrell]

Oh right, the integration tests! Yes, that would be good, wouldn’t it?

Number 1 I fixed in a previous commit, but it got re-clobbered in the midst of all the merge excitement. I’ve re-fixed it.

Number 2 was more subtle, but is also fixed. I also fixed the Rubocop complaints.