New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve developer experience for previewing docs in development #843

Merged
merged 2 commits into from Oct 11, 2018

Conversation

Projects
None yet
3 participants
@nholden
Contributor

nholden commented Oct 6, 2018

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

screen shot 2018-10-06 at 4 16 53 pm

Added to documentation?

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

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

😎

Improve developer experience for previewing docs in development
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 so we can ensure it works and is compatible 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.

timberio/gitdocs#156 (comment)
#819 (comment)
@benhalpern

This comment has been minimized.

Collaborator

benhalpern commented Oct 9, 2018

@jessleenyc @maestromac can you give this a review?

Show resolved Hide resolved package.json

@maestromac maestromac merged commit a6ff2f3 into thepracticaldev:master Oct 11, 2018

6 checks passed

WIP ready for review
Details
codeclimate All good!
Details
codeclimate/diff-coverage 100% (50% threshold)
Details
codeclimate/total-coverage 85% (0.0% change)
Details
deploy/netlify Deploy preview ready!
Details
license/cla Contributor License Agreement is signed.
Details

@nholden nholden deleted the nholden:improve-previewing-docs branch Oct 11, 2018

@maestromac

This comment has been minimized.

Collaborator

maestromac commented Oct 11, 2018

@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

This comment has been minimized.

Contributor

nholden commented Oct 11, 2018

@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 maestromac referenced this pull request Oct 12, 2018

Merged

Update JS dependencies #897

2 of 2 tasks complete
@maestromac

This comment has been minimized.

Collaborator

maestromac commented Oct 12, 2018

@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

This comment has been minimized.

Contributor

nholden commented Oct 12, 2018

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

isogram added a commit to isogram/dev.to that referenced this pull request Oct 15, 2018

@maestromac

This comment has been minimized.

Collaborator

maestromac commented Oct 19, 2018

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

This comment has been minimized.

Contributor

nholden commented Oct 19, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment