debian/changelog

+mypy (0.740-2) UNRELEASED; urgency=medium
+
+  * Incorporate high quality hand written manual pages courtesy of
+    Andrej Shadura <andrew.shadura@collabora.co.uk>
+
+ -- Michael R. Crusoe <michael.crusoe@gmail.com>  Wed, 23 Oct 2019 19:15:46 +0200
+
 mypy (0.740-1) unstable; urgency=medium
 
   * New upstream version

debian/clean

@@ -6,3 +6,7 @@ mypy/__pycache__/
 test-data/packages/typedpkg/build/
 test-data/packages/typedpkg/dist/
 test-data/packages/typedpkg/typedpkg.egg-info/
+debian/*_options.rst
+debian/dmypy.1
+debian/mypy.1
+debian/stubgen.1

debian/dmypy-check.1

+.so man1/dmypy.1

debian/dmypy-daemon.1

+.so man1/dmypy.1

debian/dmypy-hang.1

+.so man1/dmypy.1

debian/dmypy-kill.1

+.so man1/dmypy.1

debian/dmypy-recheck.1

+.so man1/dmypy.1

debian/dmypy-restart.1

+.so man1/dmypy.1

debian/dmypy-start.1

+.so man1/dmypy.1

debian/dmypy-status.1

+.so man1/dmypy.1

debian/dmypy-stop.1

+.so man1/dmypy.1

debian/dmypy.rst

+=====
+dmypy
+=====
+
+-----------------------
+mypy daemon mode client
+-----------------------
+
+:Author: Jukka Lehtosalo and contributors
+:Manual section: 1
+
+SYNOPSIS
+========
+
+**dmypy** [OPTIONS...] `COMMAND`] [COMMAND OPTIONS ...]
+
+DESCRIPTION
+===========
+
+Mypy can run as a long-running daemon (server) process allowing to perform
+type checking much faster, since program state cached from previous runs
+is kept in memory and doesn’t have to be read from the file system
+on each run. The server also uses finer-grained dependency tracking to
+reduce the amount of work that needs to be done.
+
+If you have a large codebase to check, running mypy using the mypy daemon
+can be 10 or more times faster than the regular command-line **mypy** tool,
+especially if your workflow involves running mypy repeatedly after
+small edits – which is often a good idea, as this way you’ll find
+errors sooner.
+
+Dmypy is a command-line client to send type-checking requests to the server.
+
+COMMANDS
+========
+
+start [--log-file `FILE`] [--timeout `TIMEOUT`] `ARGS`...
+*********************************************************
+
+Start a mypy daemon.
+
+Runs a new mypy daemon, passing regular mypy flags to it.
+If `--log-file` is used, directs daemon stdout/stderr to `FILE`.
+`--timeout` specifies the server shutdown timeout in seconds.
+
+stop
+****
+
+Stop a mypy daemon.
+
+Politely asks the currently running mypy daemon to go away.
+
+kill
+****
+
+Kill a mypy daemon.
+
+Kills the process of the currently running mypy daemon.
+
+restart [--log-file `FILE`] [--timeout `TIMEOUT`] `ARGS`...
+***********************************************************
+
+Restart a mypy daemon.
+
+Stops the existing and then runs a new mypy daemon, passing regular mypy flags to it.
+If `--log-file` is used, directs daemon stdout/stderr to `FILE`.
+`--timeout` specifies the server shutdown timeout in seconds.
+
+status [-v]
+***********
+
+Show a mypy daemon status.
+
+If `-v` or `--verbose` is used, prints detailed status.
+
+daemon [--timeout `TIMEOUT`] `ARGS`...
+**************************************
+
+Run a mypy daemon in the foreground, passing regular mypy flags to it.
+
+`--timeout` specifies the server shutdown timeout in seconds.
+
+check [-v] [--junit-xml `JUNIT_XML`] [--perf-stats-file `PERF_STATS_FILE`] `FILE` [`FILE` ...]
+**********************************************************************************************
+
+Check some files.
+
+Tell the currently running mypy daemon to check some files. This requires the daemon to already be running.
+
+-v, --verbose                       Print detailed status
+--junit-xml JUNIT_XML               Write junit.xml to the given file
+--perf-stats-file PERF_STATS_FILE   Write telemetry information to the given file
+
+recheck [-v] [--junit-xml `JUNIT_XML`] [--perf-stats-file `PERF_STATS_FILE`] [--update `FILE` [`FILE` ...]] [--remove `FILE` [`FILE` ...]]
+******************************************************************************************************************************************
+
+Re-check the previous list of files, with optional modifications. This requires the daemon to already be running.
+
+-v, --verbose                       Print detailed status
+--junit-xml JUNIT_XML               Write junit.xml to the given file
+--perf-stats-file PERF_STATS_FILE   Write telemetry information to the given file
+
+run [-v] [--junit-xml `JUNIT_XML`] [--perf-stats-file `PERF_STATS_FILE`] [--timeout `TIMEOUT`] [--log-file `FILE`] `ARGS`...
+****************************************************************************************************************************
+
+Check some files, (re)starting the daemon if necessary.
+
+-v, --verbose                       Print detailed status
+--junit-xml JUNIT_XML               Write junit.xml to the given file
+--perf-stats-file PERF_STATS_FILE   Write telemetry information to the given file
+--timeout TIMEOUT                   Server shutdown timeout (in seconds)
+--log-file FILE                     Direct daemon stdout/stderr to `FILE`
+
+hang
+****
+
+Hang for 100 seconds.
+
+OPTIONS
+=======
+
+``-h``, ``--help``
+   Show a help message and exit.
+
+``--status-file`` `STATUS_FILE`
+   Status file to retrieve daemon details to.
+
+``-V``, ``--version``
+   Show program’s version number and exit.
+
+SEE ALSO
+========
+
+**mypy**\(1)
+
+Full documentation is available online at: https://mypy.readthedocs.io/en/latest/mypy_daemon.html
+or locally at: `/usr/share/doc/mypy/html <file:///usr/share/doc/mypy/html>`__ (requires `mypy-doc` package).

debian/mypy.rst

+====
+mypy
+====
+
+---------------------------------
+Optional static typing for Python
+---------------------------------
+
+:Author: Jukka Lehtosalo and contributors
+:Manual section: 1
+
+SYNOPSIS
+========
+
+**mypy** [-h] [-v] [-V] [-m `MODULE`] [-p `PACKAGE`] [-c `PROGRAM_TEXT`] [`OPTIONS`...] [`FILES` ...]
+
+DESCRIPTION
+===========
+
+Mypy is a static type checker for Python 3 and Python 2.7. If you sprinkle
+your code with type annotations, mypy can type check your code and find
+common bugs. As mypy is a static analyzer, or a lint-like tool, the type
+annotations are just hints for mypy and don’t interfere when running
+your program. You run your program with a standard Python interpreter,
+and the annotations are treated effectively as comments.
+
+Using the Python 3 function annotation syntax (using the PEP 484 notation)
+or a comment-based annotation syntax for Python 2 code, you will be
+able to efficiently annotate your code and use mypy to check the code
+for common errors. Mypy has a powerful and easy-to-use type system with
+modern features such as type inference, generics, callable types, tuple
+types, union types, and structural subtyping.
+
+Mypy is invoked with the paths the user needs to check::
+
+$ mypy foo.py bar.py some_directory
+
+The directories are checked recursively to find Python source files.
+
+.. role:: ref
+.. include:: mypy_options.rst
+
+ENVIRONMENT
+===========
+
+**MYPYPATH**
+   Additional module search path entries. The format is the same as the shell's `$PATH`: one or more directory pathnames separated by colons.
+
+SEE ALSO
+========
+
+**dmypy**\(1)
+
+Full documentation is available online at: http://mypy.readthedocs.io/en/latest/getting_started.html
+or locally at: `/usr/share/doc/mypy/html <file:///usr/share/doc/mypy/html>`__ (requires `mypy-doc` package).

debian/rules

@@ -6,6 +6,7 @@ export PYBUILD_DESTDIR_python3=debian/python3-mypy
 export PYBUILD_NAME=mypy
 PPATH=$(CURDIR)
 PY3V=$(shell py3versions -dv)
+
 include /usr/share/dpkg/pkg-info.mk
 ifeq (,$(filter nodoc,$(DEB_BUILD_PROFILES)))
 	WITH += ,sphinxdoc
@@ -16,65 +17,32 @@ export DEB_BUILD_MAINT_OPTIONS=hardening=+all
 %:
 	dh $@ --with python3$(WITH) --buildsystem=pybuild
 
-override_dh_auto_build:
+ifeq (,$(filter nodoc,$(DEB_BUILD_PROFILES)))
+manpages: debian/dmypy.1 debian/mypy.1 debian/stubgen.1
+else
+manpages:
+endif
+
+debian/%.1: debian/%.rst debian/%_options.rst
+	rst2man $< > $@
+
+# create an empty file to simplify the makefile logic
+debian/dmypy_options.rst:
+	touch $@
+
+debian/mypy_options.rst: docs/source/command_line.rst
+	sed 's,The .* command line,OPTIONS,g' $< > $@
+
+debian/stubgen_options.rst: docs/source/stubgen.rst
+	sed -n -e '/stubgen --help/,$$ {/stubgen --help/d; p}' $< > $@
+
+override_dh_auto_build: manpages
 	export MYPY_USE_MYPYC=1; dh_auto_build
 ifeq (,$(filter nodoc,$(DEB_BUILD_PROFILES)))
-	PYTHONPATH=$(PPATH) help2man 'python3 -m mypy' --no-info \
-		   --version-string="${DEB_VERSION_UPSTREAM}" \
-		   --name 'Optional Static Typing for Python' > debian/mypy.1
-	sed -i 's/python3 -m mypy/mypy/g' debian/mypy.1
-	sed -i 's/python3/mypy/g' debian/mypy.1
-	sed -i 's/PYTHON3/MYPY/g' debian/mypy.1
-	PYTHONPATH=$(PPATH) help2man 'python3 -m mypy.dmypy' --no-info \
-		   --version-string="${DEB_VERSION_UPSTREAM}" \
-		   --include <(echo -e "[NAME]\ndmymy \- Client for mypy daemon mode") \
-		   > debian/dmypy.1
-	sed -i '/\.\.\./d' debian/dmypy.1 # Delete the "..."
-	PYTHONPATH=$(PPATH) help2man 'python3 -m mypy.dmypy start' --no-info \
-		   --version-string="${DEB_VERSION_UPSTREAM}" \
-		   --include <(echo -e "[NAME]\ndmypy_start \- Start a mypy daemon") \
-		   > debian/dmypy-start.1
-	PYTHONPATH=$(PPATH) help2man 'python3 -m mypy.dmypy restart' --no-info \
-		   --version-string="${DEB_VERSION_UPSTREAM}" \
-		   --include <(echo -e "[NAME]\ndmypy_restart \- Restart a mypy daemon") \
-		   > debian/dmypy-restart.1
-	PYTHONPATH=$(PPATH) help2man 'python3 -m mypy.dmypy status' --no-info \
-		   --version-string="${DEB_VERSION_UPSTREAM}" \
-		   --include <(echo -e "[NAME]\ndmypy_status \- Show a mypy daemon status") \
-		   > debian/dmypy-status.1
-	PYTHONPATH=$(PPATH) help2man 'python3 -m mypy.dmypy stop' --no-info \
-		   --version-string="${DEB_VERSION_UPSTREAM}" \
-		   --include <(echo -e "[NAME]\ndmypy_stop \- Stop a mypy daemon") \
-		   > debian/dmypy-stop.1
-	PYTHONPATH=$(PPATH) help2man 'python3 -m mypy.dmypy kill' --no-info \
-		   --version-string="${DEB_VERSION_UPSTREAM}" \
-		   --include <(echo -e "[NAME]\ndmypy_kill \- Kill a mypy daemon") \
-		   > debian/dmypy-kill.1
-	PYTHONPATH=$(PPATH) help2man 'python3 -m mypy.dmypy check' --no-info \
-		   --version-string="${DEB_VERSION_UPSTREAM}" \
-		   --include <(echo -e "[NAME]\ndmypy_check \- Type check some Python files with a mypy daemon") \
-		   > debian/dmypy-check.1
-	PYTHONPATH=$(PPATH) help2man 'python3 -m mypy.dmypy recheck' --no-info \
-		   --version-string="${DEB_VERSION_UPSTREAM}" \
-		   --include <(echo -e "[NAME]\ndmypy_recheck \- Type check the same files from the previous run") \
-		   > debian/dmypy-recheck.1
-	PYTHONPATH=$(PPATH) help2man 'python3 -m mypy.dmypy hang' --no-info \
-		   --version-string="${DEB_VERSION_UPSTREAM}" \
-		   --include <(echo -e "[NAME]\ndmypy_hang \- Hang a mypy daemon, as a debug hack") \
-		   > debian/dmypy-hang.1
-	PYTHONPATH=$(PPATH) help2man 'python3 -m mypy.dmypy daemon' --no-info \
-		   --version-string="${DEB_VERSION_UPSTREAM}" \
-		   --include <(echo -e "[NAME]\ndmypy_daemon \- Run a mypy daemon in the foreground") \
-		   > debian/dmypy-daemon.1
-	PYTHONPATH=$(PPATH) help2man 'python${PY3V} -m mypy.stubgen' --no-info \
-		   --no-discard-stderr --version-string="${DEB_VERSION_UPSTREAM}" \
-		   --include <(echo -e "[NAME]\nstubgen \- Generate draft stubs for Python modules.") \
-		   > debian/stubgen.1
 	PYTHONPATH=$(CURDIR) $(MAKE) -C docs html
 endif
 
 override_dh_auto_clean:
-	rm -f debian/*.1
 	dh_auto_clean
 ifeq (,$(filter nodoc,$(DEB_BUILD_PROFILES)))
 	$(MAKE) -C docs clean
@@ -95,3 +63,5 @@ ifeq (,$(filter nocheck,$(DEB_BUILD_PROFILES)))
 	     -o testpaths=mypy/test -o python_files=test*.py \
 	     -o python_classes= -o python_functions=
 endif
+
+.PHONY: manpages

debian/stubgen.rst

+=======
+stubgen
+=======
+
+-------------------------------------------------
+Generate draft type hint stubs for Python modules
+-------------------------------------------------
+
+:Author: Jukka Lehtosalo and contributors
+:Manual section: 1
+
+SYNOPSIS
+========
+
+**stubgen** [-h] [-py2] [-m `MODULE`] [-p `PACKAGE`] [`OPTIONS`...] [`FILES`...]
+
+DESCRIPTION
+===========
+
+Mypy is a static type checker for Python 3 and Python 2.7. Mypy includes
+the `stubgen` tool that can automatically generate stub files (`.pyi`
+files) for Python modules and C extension modules.
+
+A stub file (see PEP 484) contains only type hints for the public
+interface of a module, with empty function bodies. Mypy can use a stub
+file instead of the real implementation to provide type information for
+the module. They are useful for third-party modules whose authors have
+not yet added type hints (and when no stubs are available in typeshed)
+and C extension modules (which mypy can’t directly process).
+
+Stubgen generates *draft* stubs. The auto-generated stub files often require some manual updates, and most types will default to `Any`. The stubs will be much more useful if you add more precise type annotations, at least for the most commonly used functionality.
+
+OPTIONS
+=======
+
+.. role:: ref
+.. include:: stubgen_options.rst
+
+ENVIRONMENT
+===========
+
+**MYPYPATH**
+   Additional module search path entries. The format is the same as the shell's `$PATH`: one or more directory pathnames separated by colons.
+
+SEE ALSO
+========
+
+**mypy**\(1)
+
+Full documentation is available online at: https://mypy.readthedocs.io/en/latest/stubgen.html
+or locally at: `/usr/share/doc/mypy/html <file:///usr/share/doc/mypy/html>`__ (requires `mypy-doc` package).