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

Update docker docs #1904

Merged
merged 5 commits into from May 15, 2018

Conversation

Projects
None yet
2 participants
@toolness
Contributor

toolness commented May 14, 2018

This revamps the Docker docs in a few ways:

  • It moves less-useful Docker stuff to the bottom. At the top is now telegraphed advice to PLZ RUN ./docker-update.sh IF UR SETUP IS JACKED.

  • It adds advice on using docker-compose down -v if the above doesn't work.

  • It changes the recommended way of using pdb by documenting the solution I proposed in #1313 (comment). This required a few modifications to docker-compose.local.yml, but I don't think they should negatively affect anything.

  • It has some annoying special-case docs on installing custom dependencies to the node environment. (Unfortunately, due to the way yarn works, there's no easy way to install custom dependencies that exist only in your local setup.)

  • A few other minor copy edits.

@toolness toolness requested a review from hbillings May 14, 2018

@jseppi jseppi referenced this pull request May 14, 2018

Closed

Review and update developer documentation #1698

10 of 15 tasks complete
@hbillings

This is so much friendlier and clearer!

./docker-update.sh
```
**If you're ever having problems because `docker-compose up` explodes in an unfriendly way, it's quite likely that `./docker-update.sh` will fix it.**

This comment has been minimized.

@hbillings

hbillings May 15, 2018

Member

👌 👌

won't want to commit to git. You'll have to either make sure
not to commit those files, or undo the installation once
you're finished using the package with
`docker-compose run app yarn remove`.

This comment has been minimized.

@hbillings

hbillings May 15, 2018

Member

LOL, I was just trying to figure out the right way to do this a couple days ago!

but you can ignore that.)
4. Debug as you normally would. (If you're unfamiliar with the
debugger, here's a [handy list of `ipdb` commands][ipdb_intro].)

This comment has been minimized.

@hbillings

hbillings May 15, 2018

Member

This references ipdb, but the previous commands are for regular ol' pdb. I've pretty much only used the former, so I can't comment on how similar/different they are, but maybe we want to stick with just pdb.

This comment has been minimized.

@toolness

toolness May 15, 2018

Contributor

Oh uh good point. I've only used pdb and I hate it. According to the handy list we link to:

Even better than pdb is ipdb, a third-party replacement that retains all of pdb’s functionality and adds IPython support for the interactive shell, like tab completion, object introspection, friendlier tracebacks, color support, and a bucket of magic functions (which are out of the scope of this article)

That sounds like a win, so I will change the code example to use ipdb!

hbillings and others added some commits May 15, 2018

@toolness toolness merged commit 39c25e7 into develop May 15, 2018

2 checks passed

ci/circleci: build Your tests passed on CircleCI!
Details
codeclimate All good!
Details

@toolness toolness deleted the docker-docs branch May 15, 2018

@toolness

This comment has been minimized.

Contributor

toolness commented May 15, 2018

@hbillings just FYI, I changed another thing before merging this... Basically, the readthedocs Sphinx theme we're using has some snazzy alert-style thingys called admonitions that really make their content "pop out". Normally they are displayed by using the funky reStructuredText admonition directive but because reStructuredText is weird and we're using Markdown, there's no easy way for us to use them.

So um I used the web inspector to see what HTML elements/classes those cool admonitions were using and in 9020185 I just put the raw HTML in our Markdown. It doesn't reduce the readability of our Markdown too much and it really makes the content pop out in the rendered docs:

admonition

I thought this was particularly useful for the ./docker-update.sh advice so I figured the readability trade-off was worth it. If you disagree we can always revert it in a future PR, though!

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