ISystemtap: Added man page stap-jupyter(1)

diff --git a/NEWS b/NEWS
index 46c209fdbbf6661afb96be37d8027812897a7b35..5b00f8ba1e6134bd845be6a00b365bc87f5887ee 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -3,7 +3,7 @@
 - ISystemtap: the new interactive systemtap jupyter kernel. This provides
   a simple GUI for writing/running Systemtap scripts in an easy, incremental
   way within Jupyterlab. Added 2 news scripts, stap-jupyter-install
-  and stap-jupyter-container. See interactive-notebook/README.md.
+  and stap-jupyter-container. See stap-jupyter(1).
 
 - The new "language-server" mode, specified by "stap --language-server",
   starts a LSP server which will communicate with the client via stdio. 

diff --git a/man/Makefile.am b/man/Makefile.am
index 6368de6a528385b566e21c2cd2307aae1565f64a..b5e8cd8a3e7cd2302230b96f27d4ecc75df62780 100644 (file)
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -34,3 +34,6 @@ if BUILD_VIRT
 man_MANS += stapvirt.1
 endif
 
+if HAVE_MONITOR_LIBS
+man_MANS += stap-jupyter.1
+endif

diff --git a/man/Makefile.in b/man/Makefile.in
index 54d01cb7a1e756a56e444d0d628347796e88ddd7..b526a86365f17e7ff5c32806663cbc18f74cd9b8 100644 (file)
--- a/man/Makefile.in
+++ b/man/Makefile.in
@@ -92,6 +92,7 @@ target_triplet = @target@
 @BUILD_TRANSLATOR_TRUE@am__append_1 = stap.1 stap-prep.1 stap-report.1
 @BUILD_SERVER_TRUE@@HAVE_NSS_TRUE@am__append_2 = stap-server.8
 @BUILD_VIRT_TRUE@am__append_3 = stapvirt.1
+@HAVE_MONITOR_LIBS_TRUE@am__append_4 = stap-jupyter.1
 subdir = man
 ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
 am__aclocal_m4_deps = $(top_srcdir)/m4/ax_check_compile_flag.m4 \
@@ -412,7 +413,7 @@ AUTOMAKE_OPTIONS = no-dist foreign subdir-objects
 man_MANS = stapprobes.3stap stapfuncs.3stap stapvars.3stap \
        stapex.3stap dtrace.1 stap-merge.1 stappaths.7 stapsh.8 \
        systemtap-service.8 stapref.1 $(am__append_1) $(am__append_2) \
-       $(am__append_3)
+       $(am__append_3) $(am__append_4)
 all: all-recursive
 
 .SUFFIXES:

diff --git a/man/stap-jupyter.1 b/man/stap-jupyter.1
new file mode 100644 (file)
index 0000000..c2ccd33
--- /dev/null
+++ b/man/stap-jupyter.1
@@ -0,0 +1,99 @@
+.\" -*- nroff -*-
+.TH STAP-JUPYTER-* 1
+.SH NAME
+stap-jupyter-install   \- locally install isystemtap
+
+stap-jupyter-container \- manage an isystemtap container image
+
+.\" macros
+.de SAMPLE
+
+.nr oldin \\n(.i
+.br
+.RS
+.nf
+.nh
+..
+.de ESAMPLE
+.hy
+.fi
+.RE
+.in \\n[oldin]u
+
+..
+
+.SH SYNOPSIS
+\fBstap-jupyter-install\fR
+[\fB--remove\fR]
+[\fB--container-install\fR \fIPREFIX\fR]
+
+\fBstap-jupyter-container\fR
+[\fB--repo\fR \fIREPOSITORY\fR]
+[\fB--image\fR \fIIMAGE\fR]
+[\fB--tag\fR \fITAG\fR]
+[\fB--keyname\fR \fIKEYNAME\fR]
+--{\fBrun\fR, \fBpull\fR, \fBbuild\fR, \fBpublish\fR, \fBremove\fR}
+
+.SH DESCRIPTION
+ISystemtap is an interactive jupyter interface for the incremental writing and running 
+of Systemtap scripts.
+
+The \fIstap-jupyter-install\fR program can be used to locally install the ISystemtap
+jupyter kernel, language-server and jupyter-lab extension in ~/.systemtap/jupyter.
+Once installed, the kernel can be used with \fIjupyter-lab\fR.
+
+Alternatively the \fIstap-jupyter-container\fR program can be used to run ISystemtap
+within a container, preventing the need for any local jupyter kernel installation.
+
+.SH INSTALL OPTIONS
+The following options are supported by stap-jupyter-install. Any other option prints a short help
+message.
+.IP "\fB--remove\fR"
+Uninstall the local ISystemtap files.
+.IP "\fB--container-install\fR \fIPREFIX\fR"
+\fB[Intended For Maintainers Only]\fR This is used to specify the \fIPREFIX\fR of the install
+directory for \fIstap\fR. It is called within the container build process, and should not
+be used otherwise. 
+.SH CONTAINER OPTIONS
+The following options are supported by stap-jupyter-container. Any other option prints a short help
+message.
+.IP "\fB--repo\fR \fIREPOSITORY\fR"
+Specify which repository to use, defaults to "quay.io".
+.IP "\fB--image\fR \fIIMAGE\fR"
+Specify the image name. Defaults to "systemtap/isystemtap"
+.IP "\fB--tag\fR \fITAG\fR"
+Specify the image tag. Defaults to "latest"
+.IP "\fB--keyname\fR \fIKEYNAME\fR"
+In order for the container to run \fIstap\fR it needs to \fIssh\fR to the host. It requires
+an ssh key pair, and is specified by \fIKEYNAME\fR, which is by default "id_rsa".
+
+.SH CONTAINER COMMANDS
+The following commands are recognized by stap-jupyter-container. One of the following
+is required.
+.IP "\fB--run\fR"
+ Run the image. Pulls if not done already.
+.IP "\fB--pull\fR"
+ Pulls the image.
+.IP "\fB--build\fR"
+ Builds a local copy of the image. The repo will be "localhost". See \fIpodman\fR images.
+.IP "\fB--remove\fR"
+ Removes the image.
+.IP "\fB--publish\fR"
+ \fB[Intended For Maintainers Only]\fR This is used to publish the built image. It 
+requires write permissions to 
+.nh
+https://quay.io/systemtap/isystemtap.
+.hy
+
+.SH SEE ALSO
+.nh
+.nf
+.IR stap (1),
+.IR podman (1)
+.IR ssh (1)
+
+.SH BUGS
+Use the Bugzilla link of the project web page or our mailing list.
+.nh
+.BR http://sourceware.org/systemtap/ , <systemtap@sourceware.org> .
+.hy

diff --git a/systemtap.spec b/systemtap.spec
index 15fe5ab5367073f2797ad86dbde69110ed3f17f2..997a019cc3b6bfcb65e24b83e5ebb5c6c7a084e9 100644 (file)
--- a/systemtap.spec
+++ b/systemtap.spec
@@ -1294,6 +1294,7 @@ exit 0
 %files jupyter
 %{_bindir}/stap-jupyter-container
 %{_bindir}/stap-jupyter-install
+%{_mandir}/man1/stap-jupyter.1*
 %dir %{_datadir}/systemtap
 %{_datadir}/systemtap/interactive-notebook
 %endif