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

Add docs for linting, type checking, and editor integration #1992

Merged
merged 4 commits into from Jun 5, 2018

Conversation

Projects
None yet
3 participants
@toolness
Contributor

toolness commented Jun 1, 2018

This PR:

  • Fixes #1799.
  • Fixes #1959.
  • Removes docs/changelog.md, which was erroneously added in a2d090e. This file used to be copied from the root directory as part of the documentation's Makefile but we got rid of that in #1866, and I suspect it was accidentally committed to the repository because docs/changelog.md was no longer in our .gitignore.

@toolness toolness requested a review from hbillings Jun 1, 2018

@@ -0,0 +1,59 @@
## Editor integration
In practice, it's often convenient to install editor integrations for

This comment has been minimized.

@tbaxter-18f

tbaxter-18f Jun 4, 2018

Member

I'd strike "In practice" since there is no "in theory", and just start with "It's often convenient to install. Also, I don't think you need the comma after "languages"

This comment has been minimized.

@toolness

toolness Jun 4, 2018

Contributor

Good point, will change this!

### Python
Setting up CALC's Python environment can be accomplished by installing
the version of Python 3 specified in [runtime.txt](../runtime.txt). You

This comment has been minimized.

@tbaxter-18f

tbaxter-18f Jun 4, 2018

Member

Is they py3 version changing often enough to justify bouncing them to runtime.txt? Could we just say "Python 3.x" or "a version of python greater than 3.x"?

This comment has been minimized.

@toolness

toolness Jun 4, 2018

Contributor

Yeah, I try to avoid doc rot when possible, and honestly I don't think this documentation is going to be visited terribly often, as it's fairly advanced functionality. Links to in-repo files are checked at doc build time to ensure they don't go stale, and the user only has to click on the link to see what the python version is, so I think the trade-off is worth it...

@@ -0,0 +1,97 @@
## Linting and strong typing
CALC uses a number of linters to maintain the style and hygeine of its

This comment has been minimized.

@tbaxter-18f

tbaxter-18f Jun 4, 2018

Member

Typo: hygiene

@tbaxter-18f

This comment has been minimized.

Member

tbaxter-18f commented Jun 4, 2018

I approved, but I may not have write access, so my review may not have been counted. Anyways, +1 from me.

@toolness

This comment has been minimized.

Contributor

toolness commented Jun 4, 2018

Oh thanks @tbaxter-18f ! It looks like you don't actually have the status to be "the approver" or whatever, but that's ok, I'd like @hbillings to weigh in on this one too if that's ok.

@hbillings

excellent!

@@ -1,344 +0,0 @@
# Change log

This comment has been minimized.

@hbillings

hbillings Jun 4, 2018

Member

d'oh, sorry about this!

This comment has been minimized.

@toolness

toolness Jun 4, 2018

Contributor

hehe no worries, i figured it'd come back to haunt us somehow :)

At this point, you should be able to install any editor integrations for
JavaScript-related code, and they should work as expected.

This comment has been minimized.

@hbillings

hbillings Jun 4, 2018

Member

Would it make sense to link to the linters bit here? Reading through this, my first question was, "Do we have any recommended integrations"?

This comment has been minimized.

@toolness

toolness Jun 4, 2018

Contributor

Err, that is a huge question because it totally depends on what the user's editor preferences are, and it could easily become out-of-date. And it's further complicated by the fact that we have lots of different linting/typing tools, so that means there could be several plugins that need to be installed per editor. For instance, on VSCode, I have to use their python plugin, which supports both mypy and flake8 integration, and then I use the official typescript plugin and the eslint plugin on top of that. Blorg.

This comment has been minimized.

@toolness

toolness Jun 4, 2018

Contributor

I mean, that said, we could provide advice on what to google for, maybe? Like if i were using editor "SuperEdit" and i wanted flake8 support, I would google for "SuperEdit flake8", and odds are the first hit would be pretty useful (in fact, I just did this for "vscode flake8" and it took me to the docs for the python extension I use).

This comment has been minimized.

@toolness

toolness Jun 4, 2018

Contributor

Oh wait, I think I completely misinterpreted what you were saying.

YES, it would make sense to link to the linters bit here, lol. I will add that.

This comment has been minimized.

@hbillings

hbillings Jun 4, 2018

Member

LOL, I was writing a comment about how I just meant that "editor integration" seems like a potentially confusing term, and maybe it would just be useful to explain that a bit further by saying, "for instance! there are integrations for lots of the linters and whatnot we use, and you can read about those here!"

This comment has been minimized.

@toolness

toolness Jun 4, 2018

Contributor

Hehe totally! What do you think of the changes I just made in 43900bc? Good, or too easy to miss?

This comment has been minimized.

@toolness

toolness Jun 4, 2018

Contributor

I just realized that without the hyperlink, it looks like I'm asking you about changes I made in 43,900 BC.

This comment has been minimized.

@hbillings

hbillings Jun 4, 2018

Member

WHAT DID YOU DO TO THE DINOSAURS

This comment has been minimized.

@hbillings

hbillings Jun 4, 2018

Member

I think that's good!

@toolness toolness merged commit 8632329 into develop Jun 5, 2018

3 checks passed

ci/circleci: build Your tests passed on CircleCI!
Details
codeclimate All good!
Details
codeclimate/total-coverage 92% (0.0% change)
Details

@toolness toolness deleted the linting-and-editors-docs branch Jun 5, 2018

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