[med-svn] [Git][med-team/mypy][master] 3 commits: Replace help2man-generated pages by human-written ones
Michael R. Crusoe
gitlab at salsa.debian.org
Wed Oct 23 18:46:37 BST 2019
Michael R. Crusoe pushed to branch master at Debian Med / mypy
Commits:
cabc3a2e by Andrej Shadura at 2019-09-11T15:09:05Z
Replace help2man-generated pages by human-written ones
Instead of running help2man which produces mediocre-looking manual
pages, provide three human-written manpage templates including bits
from the actual documentation written in ReST.
Link the dmypy subcommands pages to the main dmypy page.
- - - - -
66016b7f by Michael R. Crusoe at 2019-10-23T17:14:49Z
Merge branch 'andrewsh/mypy-better-manpages'
- - - - -
202c1243 by Michael R. Crusoe at 2019-10-23T17:16:34Z
document Andrew's contribution; thanks!
- - - - -
15 changed files:
- debian/changelog
- debian/clean
- + debian/dmypy-check.1
- + debian/dmypy-daemon.1
- + debian/dmypy-hang.1
- + debian/dmypy-kill.1
- + debian/dmypy-recheck.1
- + debian/dmypy-restart.1
- + debian/dmypy-start.1
- + debian/dmypy-status.1
- + debian/dmypy-stop.1
- + debian/dmypy.rst
- + debian/mypy.rst
- debian/rules
- + debian/stubgen.rst
Changes:
=====================================
debian/changelog
=====================================
@@ -1,3 +1,10 @@
+mypy (0.740-2) UNRELEASED; urgency=medium
+
+ * Incorporate high quality hand written manual pages courtesy of
+ Andrej Shadura <andrew.shadura at collabora.co.uk>
+
+ -- Michael R. Crusoe <michael.crusoe at 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
=====================================
@@ -0,0 +1 @@
+.so man1/dmypy.1
=====================================
debian/dmypy-daemon.1
=====================================
@@ -0,0 +1 @@
+.so man1/dmypy.1
=====================================
debian/dmypy-hang.1
=====================================
@@ -0,0 +1 @@
+.so man1/dmypy.1
=====================================
debian/dmypy-kill.1
=====================================
@@ -0,0 +1 @@
+.so man1/dmypy.1
=====================================
debian/dmypy-recheck.1
=====================================
@@ -0,0 +1 @@
+.so man1/dmypy.1
=====================================
debian/dmypy-restart.1
=====================================
@@ -0,0 +1 @@
+.so man1/dmypy.1
=====================================
debian/dmypy-start.1
=====================================
@@ -0,0 +1 @@
+.so man1/dmypy.1
=====================================
debian/dmypy-status.1
=====================================
@@ -0,0 +1 @@
+.so man1/dmypy.1
=====================================
debian/dmypy-stop.1
=====================================
@@ -0,0 +1 @@
+.so man1/dmypy.1
=====================================
debian/dmypy.rst
=====================================
@@ -0,0 +1,137 @@
+=====
+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
=====================================
@@ -0,0 +1,55 @@
+====
+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
=====================================
@@ -0,0 +1,51 @@
+=======
+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).
View it on GitLab: https://salsa.debian.org/med-team/mypy/compare/dadfefe707135f227571bbdf526116c3d544f6c6...202c124313e0859008490fa7e5df6ff77104b9f3
--
View it on GitLab: https://salsa.debian.org/med-team/mypy/compare/dadfefe707135f227571bbdf526116c3d544f6c6...202c124313e0859008490fa7e5df6ff77104b9f3
You're receiving this email because of your account on salsa.debian.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/debian-med-commit/attachments/20191023/e037cfa5/attachment-0001.html>
More information about the debian-med-commit
mailing list