Improve developer experience for previewing docs in development

[nholden]

What type of PR is this?

• Refactor
• Feature
• Bug Fix
• Documentation Update

Description

There is no documentation on how to preview the docs in development. It turns out that it requires installing an npm package globally, navigating to a directory, and running a command. The @next version of that npm package, gitdocs, is currently broken, so even if someone knew all the steps to preview the docs, it's likely they would hit an error.

This change does a few things to help make previewing docs in development a less painful experience:

1. It adds gitdocs as a dev dependency so that we can control the version and ensure it works with our configs.
2. It adds a Yarn script so that serving the docs is a one liner for developers and easily configurable if we need to change the implementation in the future.
3. It adds documentation about how to preview the docs.

Desktop Screenshot

Added to documentation?

• docs.dev.to
• readme
• no documentation needed

What gif best describes this PR or how it makes you feel?

[benhalpern]

@jessleenyc @maestromac can you give this a review?

[maestromac]

@nholden I can't figure out why but for some reason, having gitdoc as a dependency is failing our deployment. I ran this build twice and both time fail with the same error. The subsequent build with gitdoc removed passed 🤷‍♂️.

[nholden]

@maestromac Do we have a way of checking what the NODE_ENV environment variable is set to during deployment? If it's production, Yarn shouldn't install development dependencies. Alternatively, we could run yarn install --production instead of yarn install.

[maestromac]

@nholden Thank you for pointing that out! We have assumed that Rails would automatically set NODE_ENV based on RAILS_ENV but we were wrong. I will add back gitdoc as a devDependencies in the upcoming pr.

[nholden]

@maestromac No problem, and thanks for following up!

I'm not sure what dev.to's deployment to Heroku looks like, but I believe if you include the heroku/nodejs buildpack before the heroku/ruby buildpack, NODE_ENV should automatically be set to production. See Using Multiple Buildpacks for an App if you're interested.

[maestromac]

Hey @nholden sorry to ping you again. I've tried to add Gitdoc back but the CI keep failing. Want to give you a heads up that I might not have it as a dependency and revert the package.json changes.

[nholden]

No worries!

That's a bummer that CI isn't working. It looks like Travis is still installing Yarn devDependencies, which indicates to me that NODE_ENV is still "development". That seems like it would be worth addressing.

If we exhaust all options for including Gitdoc as a dependency, maybe we could consider writing a script outside of Yarn that installs Gitdoc, navigates to the right directory, and runs gitdocs serve to save folks a couple steps.