Jest: Why are "Docs" and "API" separated?

Created on 21 Apr 2017 · 13Comments · Source: facebook/jest

It always takes me a while to find the API reference on Jest website. I couldn't figure out why (usually I'd Cmd+F to "API" in the footer and click on it). Only today did I consciously realize that "Docs" page doesn't include "API" in the sidebar, and instead "API" is a completely separate top-level item.

I was curious: why? I'd totally expect "API Reference" to be a subsection of Docs. Especially given that it documents the config format (I wouldn't think of clicking "API" to find it).

Can we merge them?

Documentation

Source

gaearon

Most helpful comment

The separation was meant to minimize clutter in the sidebar, but in practice I've run into the same issues raised by @gaearon. Let's display both in the sidebar.

hramos on 24 Apr 2017

👍3

All 13 comments

I think it makes sense as a top level nav item, (and I agree that Reference is a better name than API on the top level here) - to aid people that went down the same route, the reference's sidebar could also be added to the sidebar on the docs so you'd get:

Getting Started
Using Matchers
Testing Asynchronous Code
Setup and Teardown
Mock Functions
More Resources

Guides
Snapshot Testing
Testing React Apps
Testing React Native Apps
An Async Example
Timer Mocks
Manual Mocks
Using with webpack
Migrating to Jest
Testing other frameworks
Troubleshooting

API Reference
Globals
Expect
Mock Functions
The Jest Object
Configuring package.json
Jest CLI Options

On any docs page.

orta on 21 Apr 2017

Yes, that’s what I would expect 👍

gaearon on 21 Apr 2017

cc @hramos – can we add "API" to the docs sidebar?

cpojer on 21 Apr 2017

cpojer @gaearon @orta We could merge the 'reference' and 'docs' document chains into one and have the API or Reference link at top link directly to Api/Globals.

ericnakagawa on 21 Apr 2017

I have a PR that adds API to the docs, but depends on my PR #3337 being accepted since the file routes change.

ericnakagawa on 21 Apr 2017

The separation was meant to minimize clutter in the sidebar, but in practice I've run into the same issues raised by @gaearon. Let's display both in the sidebar.

hramos on 24 Apr 2017

👍3

I was also confused by the separate /en/ version of the docs:

http://facebook.github.io/jest/docs/troubleshooting.html#unresolved-promises
vs.
http://facebook.github.io/jest/docs/en/troubleshooting.html#unresolved-promises

(they point to different content)