Doc Revamp

[mikemhenry]

There are a few different "phases" to updating our docs.

1. First lets make sure our current doc strings get linted in the source code
   1.1 Find a linter
   1.2 Fix issues the linter finds
   1.3 Push fixes + include linter into CI

Later we can use the linter to enforce things like requiring doc strings for every function.

Second phase is to collate the user feedback we have received via issues on github and interactions on our gitter chat. The goal is to identify any systemic issues we have/are making with our documentation.  Some examples:

Feature discovery: Right now users are exposed to the features we showcase in the tutorial and use those features, but due to missing methods/classes in API.rst, browsing our API documentation doesn't let someone discover everything that you can do
Third phase: Take the collated feedback and make corrections to our developer documentation to ensure that we have some controls in place to prevent systemic issues identified in phase two.

[mikemhenry]

The first step is also a good first issue for someone who wants to poke at our CI system a bit + make some relatively straightforward edits to our documentation formatting. I would start looking at some of these:

https://github.com/PyCQA/pydocstyle
https://gitlab.com/pycqa/flake8-docstrings
https://github.com/terrencepreilly/darglint

From it a quick glace they all might to slightly different things. Something to consider is for the first step we just want some sort of checking that our doc strings are formatted according to the numpy style of document strings. I know some tools provide functionality to test examples in doc strings, but what we are looking for at this stage is just a formatting test.

[mikemhenry]

To make another pitch why someone might want to work with me on this issue: It will require you to touch the entire code base in an organic way :)

[mikemhenry]

See issue #74 for deciding what style we want to follow.

[mikemhenry]

As a test we will pick a single module to make sure the tooling works and see how it works in the CI

[vyasr]

Related issue: glotzerlab/signac-flow#193