Add Atom's API docs to the Flight Manual

[jasonrudolph]

This pull request aims to bring the Atom API reference docs into the Flight Manual. These docs currently reside at https://atom.io/docs/api, and we'd like for them to move them into this repository so that all of Atom's docs are consolidated in a single place.

TODO

• [x] Enhance the build to generate API docs at /api/:version/:class (for example: /api/v1.38.2/AtomEnvironment)
• [x] Enhance the search index to include the API docs
  • [x] instance methods (aeee307bf27aaf0a2e611084e86cb8e5d99c0202)
  • [x] instance properties (fb77ad9f30c6780980f6a77cf6fad982508c9b5a)
  • [x] class methods (4599da9b4c3b1401858eb6a66bca4ae17e143592)
  • [x] the class itself (0a417a8d00349731074246a4de21240f89b382eb)
• [x] Show the list of classes in the left sidebar (to match current behavior on https://atom.io/docs/api)
• [x] When navigating to the root URL (/api), show the docs for the current stable version (https://github.com/atom/flight-manual.atom.io/compare/387eeee4488f13be1eb610370ef495d9bbce98b9...de1e02a850721dfcf1cf2a5e8ee322c09b92b5eb)
• [x] Provide drop-down menu for choosing the Atom version whose docs you want to view
• [x] Compare the output side-by-side with the content at https://atom.io/docs/api and fix any bugs
  • [x] "Essential" classes should include an "Essential" label at the top of the page [screenshot] (60234aa2018795ae0b3b0d03a87f12630c01d051)
  • [x] Code samples should be rendered with syntax highlighting [screenshot]
  • [x] Optional parameter should have an "optional" badge [screenshot] (5a0f3900776dec193b301024f42502569949cd61)
  • [x] "Extended" methods should be grouped together in an "Extended Methods" subsection, and they should be hidden by default [screenshot]

/cc @lee-dohm @as-cii

[jasonrudolph]

• [ ] When navigating to the root URL (/api), show the docs for the current stable version

@lee-dohm @as-cii: I've just about got this ☝️ working locally. I've gotta head out for dinner, but I'm hoping to get this pushed up tomorrow morning.

[lee-dohm]

• [ ] Show the list of classes in the left sidebar (to match current behavior on https://atom.io/docs/api)

I got this working for both the main table of contents at / and in the sidebar of each page. I sandwiched the API docs between the chapters and the appendices. I fiddled around with the memoization to speed things up and it's pretty quick for going through 140+ versions of API docs.

Right now though, the class links all refer to /api/latest/ClassName/index.html so either we'll need to fiddle with the routes rules in Rules or, if that won't work, I can quickly redo it to put the latest version number in the URL.

Oh, and the links pointing to invalid references is why the build is failing 😊

[lee-dohm]

Updated the links to use a hardcoded version.

[jasonrudolph]

• [ ] Compare the output side-by-side with the content at https://atom.io/docs/api and fix any bugs

I've compared the current content at https://atom.io/docs/api to the content rendered by this branch, and I've updated the issue body to list the differences that I've noticed so far.

[jasonrudolph]

@lee-dohm: I think this is looking pretty good now. Would you mind trying out these changes to see if there's anything that's essential to change before we ship?

Note: Given the size of this diff and how long this branch has been in progress, I think we should lean heavily toward getting to a reasonable production "v1" of these changes as soon as possible and deferring any enhancements to separate pull requests. 😇

[lee-dohm]

I'll take a look at this first thing in my morning tomorrow. Thanks so much for all the work driving this forward @jasonrudolph and @as-cii 🙇 I agree that a reasonable v1 is the appropriate action here.

[lee-dohm]

This looks great! I've marked the PR as ready for review while I dig deeper into it.

[calebmeyer]

From taking a quick look at the website:

• I like the search, although I wish the indexing were breadth first instead of depth first. Searching "marker" gets you lots of methods under MarkerLayer, but nothing about DisplayMarker.
• I think our sidebar nav is getting a bit long. I'd almost rather see the headers be collapsible, even if they start expanded. One of the things I liked about the separate API docs was that I could see quite a few of the classes without any scrolling. Now even veterans have to scroll quite a bit to get past the sections on installing atom, and editing text, etc.
• I didn't see any straight up bugs from clicking around. The mac/windows/linux selector works, all the highlighting looks right, all the links worked, including source code links. :+1:

Edit: I'm also in favor of a quick v1. These are definitely not show stoppers. If you'd like, I can open issues for them.

[jasonrudolph]

Thanks for the review! I'm gonna roll this out now.

Despite all our testing and code review, I anticipate us discovering at least some issues in real-world use due to the sheer magnitude of this change. To minimize the impact, we'll keep an eye on issues filed over the next few days, and we'll try to respond as quickly as possible to any problems that come up.