Improve daemon docs; add docs for dmypy suggest #8032
Conversation
docs/source/mypy_daemon.rst
Outdated
|
|
||
| .. option:: --status-file FILE | ||
|
|
||
| Status file to retrieve daemon details. This is normally a JSON file |
There was a problem hiding this comment.
Suggested edit: "Use FILE as the status file for storing daemon runtime state. ..."
docs/source/mypy_daemon.rst
Outdated
|
|
||
| .. option:: --timeout TIMEOUT | ||
|
|
||
| Server shutdown timeout (in seconds). Only available for ``start``, |
There was a problem hiding this comment.
Suggested edit: Automatically shut down server after TIMEOUT seconds of inactivity.
docs/source/mypy_daemon.rst
Outdated
| .. option:: --fswatcher-dump-file FILE | ||
|
|
||
| Collect information about the current file state. Only available for | ||
| ``status`` command. |
There was a problem hiding this comment.
I think that this description is not detailed enough to be useful. I think that it's fine to leave this undocumented for now. Altarnatively, at least the purpose of this information and the structure/contents of it should probably be documented.
docs/source/mypy_daemon.rst
Outdated
|
|
||
| .. option:: --perf-stats-file FILE | ||
|
|
||
| Write performance telemetry information to the given file. Only available |
There was a problem hiding this comment.
Nit: Tthis is not telemetry, since it's only written to a local file.
Suggested edit: "Write performance profiling information to FILE.
| .. option:: --update FILE | ||
|
|
||
| Files in the run to add or check again, may be repeated. Default: all | ||
| files from the previous run. Only available for ``recheck`` command. |
There was a problem hiding this comment.
Give some motivation for why somebody might want to use this option. Something about speeding up runs if there are thousands of files, and maybe suggest using file events to find the modified files.
Maybe also mention that this option is never required and is only available for speeding things up.
| Files to remove from the run, may be repeated. Only available for | ||
| ``recheck`` command. | ||
|
|
||
| Static inference of annotations |
There was a problem hiding this comment.
Maybe move this to a separate rst file, since this is quite distinct from other features provided by dmypy, and mostly relevant for users that are going to write integrations (since the low-level UX is kind of hard to use).
There was a problem hiding this comment.
I think we can keep it in the same file for now. It is anyway at the very end and it is probably OK to attract some attention to it.
Also I can't find a good name for a section that would look good in table of contents with the daemon. I think we can move it to a separate file when we will add dmypy reveal, then it will look more natural.
docs/source/mypy_daemon.rst
Outdated
|
|
||
| Running this command will produce a suggested signature in the format | ||
| ``(param_type_1, param_type_2, ...) -> ret_type``. This may be used by IDEs | ||
| or similar tools to propose to user and/or insert the annotation into file. |
There was a problem hiding this comment.
As I mentioned earlier, this information is key and should probably be presented earlier.
Maybe discuss what happens to arguments with default values, *args and **kwargs.
docs/source/mypy_daemon.rst
Outdated
|
|
||
| .. option:: --json | ||
|
|
||
| Use JSON format to output the signature, so that `PyAnnotate`_ can use it |
There was a problem hiding this comment.
Suggested edit: "Output the signature as JSON, so that ..."
Maybe also give an example of the JSON?
docs/source/mypy_daemon.rst
Outdated
| .. option:: --use-fixme NAME | ||
|
|
||
| A dummy name to use instead of plain ``Any`` for types that cannot | ||
| be inferred. |
There was a problem hiding this comment.
Maybe add some motivation for this feature.
docs/source/mypy_daemon.rst
Outdated
|
|
||
| root = format_id(0) | ||
|
|
||
| Mypy can infer that ``format_id()`` takes an ``int`` and returns a ``str``. |
There was a problem hiding this comment.
Maybe explain the algorithm in little detail, such as mentioning that mypy looks at call sites and the function definition to infer types.
No description provided.