Add Atom's API docs to the Flight Manual #541

jasonrudolph · 2019-06-27T16:18:51Z

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

/cc @lee-dohm @as-cii

Replace the `split_api_json` Rake task with equivalent logic in `gulpfile.js`, so that `npm run gulp` continues to provide the end-to-end build process.

Prior to this change, the the 'nanoc:compile' gulp task attempted to store the complete output of `nanoc:compile` in a string, which resulted in a "stdout maxBuffer exceeded" error. By using `spawn` instead of `exec`, we can pipe the output of `bundle exec nanoc compile` to STDIO and thus avoid trying to fit it all in a string. Example build failure: https://travis-ci.org/atom/flight-manual.atom.io/builds/550937870#L3656

Fixes the error seen at https://travis-ci.org/atom/flight-manual.atom.io/builds/550959348#L7116

Prior to this change, we were getting the following failure on CI: > No output has been received in the last 10m0s, this potentially > indicates a stalled build or something wrong with the build itself. > ... > The build has been terminated This was due to the `run_proofer` task running for more than 10 minutes with no output. To prevent that situation, this commit introduces two changes: 1. Split up the proofer work. Invoke HTMLProofer on each directory separately, so that the `run_proofer` task reports intermediate progress. Instead of waiting until _all_ directories have been proofed before outputting any results, it will now output results for each directory immediately after proofing that directory. 2. Don't run HTMLProofer on the API docs. Checking all external links for all versions of the API docs would likely take a l-o-n-g time. I don't think we want our builds taking that long. If we _do_ want to run the proofer on all versions of the API docs, perhaps it could happen as part of a nightly build, as opposed to happening on every push. Example build failure: https://travis-ci.org/atom/flight-manual.atom.io/builds/550971951#L7122

Enhance build to process API JSON files for Atom 1.0.0 and newer

Co-authored-by: Antonio Scandurra <[email protected]>

Co-Authored-By: Antonio Scandurra <[email protected]>

Note: The code samples emitted by this change are not yet rendered with syntax highlighted.

This reverts commit 22558dd and adopts an alternative approach to the problem. We continue to *NOT* run the link checker on the API docs (for the reasons described in the commit messages for 22558dd), but we run the HTMLProofer on the root of the output directory, so that internal links can be properly resolved.

With these changes, we populate the search index with all instance methods present in the latest version of Atom. Next up, we'll need to add classes, class methods, and instance properties to the search index. Co-Authored-By: Antonio Scandurra <[email protected]>

Co-Authored-By: Antonio Scandurra <[email protected]>

jasonrudolph · 2019-07-16T21:19:21Z

@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 · 2019-07-16T22:42:02Z

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.

With the introduction of kramdown in 73b0e94, we started interpreting newline characters as hard wraps, which was causing paragraphs to not take advantage of all the available screen real estate. Documentation is usually hard-wrapped for readability purposes when navigating source code, but those concerns don't apply when viewing the same documentation in a web browser. This commit fixes the visual glitch illustrated above by supplying `hard_wrap: false` to kramdown-gfm. I verified that this doesn't affect the rendering of other markdown constructs such as code block syntax highlighting.

This ensures that Safari doesn't apply a custom style that prevents the text box from being displayed correctly.

lee-dohm · 2019-07-17T17:56:02Z

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

calebmeyer · 2019-07-17T19:05:16Z

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. 👍

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.

calebmeyer · 2019-07-17T19:11:06Z

layouts/search.json

@@ -0,0 +1,58 @@
+{


Why don't we append .erb on these files? It would make them more likely to syntax highlight correctly in whatever editor you're using, including github web.

Fair point. Would you mind opening an issue for this?

Opened #549

lib/temp.rb

layouts/api-class.html

calebmeyer · 2019-07-17T19:43:37Z

assets/javascripts/search.js

+  bindQuicksearchMousedown() {
+    $(".autocomplete-results a").each(function(_, el) {
+      $(el).bind("mousedown", function(event) {
+        event.preventDefault();


Just preventing the default and returning? I'm assuming this is so the anchors don't try to visit their hrefs. Should we use a different element like <button> in that case to be more semantically accurate?

I think that's a valid change but probably should be put off until after this is deployed. Would you mind opening an issue?

Opened #550

calebmeyer · 2019-07-17T19:46:30Z

assets/javascripts/search.js

@@ -0,0 +1,218 @@
+$(document).ready(function() {


There's a shorthand for this. Any function given directly to the jQuery function is called on document ready.

Reference

calebmeyer

+1 🚢

lee-dohm

Unless someone else sees something I missed, this looks good to go to me 🚀

jasonrudolph · 2019-07-26T13:40:05Z

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.

lee-dohm and others added 30 commits April 30, 2019 10:14

Create Rake tasks to download and split API data

786dd03

Replicate class page title

8c9fe2d

Add description and section headers

3ec7b61

Add basic rendering of instance properties

ca5643e

Add summary and description sections to methods

e2ad79e

Add class and method reference linking

c2d23c5

Fix arguments and return value tables

4b98ceb

Create a content column in API docs so that things flow properly

1c85628

Add atom-api.json files from v1.0.0 to present (v1.38.2)

6ccef21

🔥 Remove temporary Rake task for downloading historical API files

069d94d

Teach split_api_json Rake task to process files in data/apis-by-version

0984b6f

Add colon indicators to properties

8bc9122

Move JSON splitting from Rake to Gulp

42c10c6

Replace the `split_api_json` Rake task with equivalent logic in `gulpfile.js`, so that `npm run gulp` continues to provide the end-to-end build process.

🔥 Remove unused arg

8595b00

Gracefully ignore any non JSON files in data/apis-by-version dir

3d25e59

Signal completion of "extract_api_docs_data" task

76a088c

Fixes the error seen at https://travis-ci.org/atom/flight-manual.atom.io/builds/550959348#L7116

Merge pull request #537 from atom/jr/api-docs

2c08ae9

Enhance build to process API JSON files for Atom 1.0.0 and newer

Merge remote-tracking branch 'origin/master' into api-docs

399c712

Linkify instance property names

189c8bd

Co-authored-by: Antonio Scandurra <[email protected]>

Toggle display of instance property description onclick

a9df28e

Co-Authored-By: Antonio Scandurra <[email protected]>

Honor URL hash to display instance property description

8e119a3

Co-Authored-By: Antonio Scandurra <[email protected]>

Linkify method names and toggle details onclick

6cdbad6

Co-Authored-By: Antonio Scandurra <[email protected]>

Render class-level examples

4649175

Note: The code samples emitted by this change are not yet rendered with syntax highlighted.

Fix URL to API docs in search index

74475a7

Co-Authored-By: Antonio Scandurra <[email protected]>

Fix ellipsis

b0526cd

Add instance properties to search index

fb77ad9

jasonrudolph added 2 commits July 16, 2019 17:07

Align version select box and search input field

0b7fde1

Prefix version label with 'v'

f6c1ff9

jasonrudolph marked this pull request as ready for review July 16, 2019 21:14

jasonrudolph requested a review from lee-dohm July 16, 2019 21:14

Antonio Scandurra added 2 commits July 17, 2019 11:52

Replace input type from "search" to "text"

9f85a96

This ensures that Safari doesn't apply a custom style that prevents the text box from being displayed correctly.

lee-dohm marked this pull request as ready for review July 17, 2019 17:55

calebmeyer reviewed Jul 17, 2019

View reviewed changes

lib/temp.rb Outdated Show resolved Hide resolved

calebmeyer reviewed Jul 17, 2019

View reviewed changes

lib/temp.rb Outdated Show resolved Hide resolved

calebmeyer reviewed Jul 17, 2019

View reviewed changes

layouts/api-class.html Outdated Show resolved Hide resolved

calebmeyer reviewed Jul 17, 2019

View reviewed changes

calebmeyer approved these changes Jul 17, 2019

View reviewed changes

lee-dohm added 2 commits July 17, 2019 13:27

Remove commented-out code

1ec6b44

Specify which version of Node to use

47cbabf

calebmeyer mentioned this pull request Jul 17, 2019

Append .erb to ERB files so they syntax highlight better #549

Open

Inline functions that aren't used outside of temp.rb

92981c2

calebmeyer mentioned this pull request Jul 17, 2019

Use Semantic HTMLements #550

Open

lee-dohm approved these changes Jul 17, 2019

View reviewed changes

jasonrudolph added 2 commits July 25, 2019 14:03

Merge 'origin/master' into api-docs

9ee89a4

Add data/apis-by-version/v1.39.1.json

7b48541

jasonrudolph merged commit 8185516 into master Jul 26, 2019

jasonrudolph deleted the api-docs branch July 26, 2019 13:40

jasonrudolph mentioned this pull request Jul 26, 2019

⬇️ [email protected] #554

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Atom's API docs to the Flight Manual #541

Add Atom's API docs to the Flight Manual #541

jasonrudolph commented Jun 27, 2019 •

edited

Loading

jasonrudolph commented Jul 16, 2019

lee-dohm commented Jul 16, 2019

lee-dohm commented Jul 17, 2019

calebmeyer commented Jul 17, 2019 •

edited

Loading

calebmeyer Jul 17, 2019

lee-dohm Jul 17, 2019

calebmeyer Jul 17, 2019

calebmeyer Jul 17, 2019

lee-dohm Jul 17, 2019

calebmeyer Jul 17, 2019

calebmeyer Jul 17, 2019

calebmeyer left a comment

lee-dohm left a comment

jasonrudolph commented Jul 26, 2019

Add Atom's API docs to the Flight Manual #541

Add Atom's API docs to the Flight Manual #541

Conversation

jasonrudolph commented Jun 27, 2019 • edited Loading

TODO

jasonrudolph commented Jul 16, 2019

lee-dohm commented Jul 16, 2019

lee-dohm commented Jul 17, 2019

calebmeyer commented Jul 17, 2019 • edited Loading

calebmeyer Jul 17, 2019

Choose a reason for hiding this comment

lee-dohm Jul 17, 2019

Choose a reason for hiding this comment

calebmeyer Jul 17, 2019

Choose a reason for hiding this comment

calebmeyer Jul 17, 2019

Choose a reason for hiding this comment

lee-dohm Jul 17, 2019

Choose a reason for hiding this comment

calebmeyer Jul 17, 2019

Choose a reason for hiding this comment

calebmeyer Jul 17, 2019

Choose a reason for hiding this comment

calebmeyer left a comment

Choose a reason for hiding this comment

lee-dohm left a comment

Choose a reason for hiding this comment

jasonrudolph commented Jul 26, 2019

jasonrudolph commented Jun 27, 2019 •

edited

Loading

calebmeyer commented Jul 17, 2019 •

edited

Loading