Skip to content

Commit

Permalink
Produce man pages using sphinx
Browse files Browse the repository at this point in the history
Previously to create manual page for bundled programs, we use help2man
to create man page from program's help output.  Then our man2rst.py
script converts man page to rst document.  Sphinx generates html from
rst documents.

Now help2rst.py produces rst document from programs output.  We use
Sphinx solely to produce both man pages and html files.
  • Loading branch information
tatsuhiro-t committed Jan 9, 2015
1 parent b2411d9 commit a3dcf1e
Show file tree
Hide file tree
Showing 24 changed files with 1,311 additions and 754 deletions.
2 changes: 1 addition & 1 deletion doc/Makefile.am
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@ text:
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."

man:
man: apiref.rst
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
Expand Down
10 changes: 8 additions & 2 deletions doc/conf.py.in
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ master_doc = 'index'

# General information about the project.
project = u'nghttp2'
copyright = u'2012, 2014, Tatsuhiro Tsujikawa'
copyright = u'2012, 2015, Tatsuhiro Tsujikawa'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
Expand Down Expand Up @@ -242,6 +242,12 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'nghttp2', u'nghttp2 Documentation',
('nghttp.1', 'nghttp', u'HTTP/2 experimental client',
[u'Tatsuhiro Tsujikawa'], 1),
('nghttpd.1', 'nghttpd', u'HTTP/2 experimental server',
[u'Tatsuhiro Tsujikawa'], 1),
('nghttpx.1', 'nghttpx', u'HTTP/2 experimental proxy',
[u'Tatsuhiro Tsujikawa'], 1),
('h2load.1', 'h2load', u'HTTP/2 benchmarking tool',
[u'Tatsuhiro Tsujikawa'], 1)
]
125 changes: 98 additions & 27 deletions doc/h2load.1
Original file line number Diff line number Diff line change
@@ -1,75 +1,146 @@
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.46.4.
.TH H2LOAD "1" "January 2015" "h2load nghttp2/0.7.0" "User Commands"
.\" Man page generated from reStructuredText.
.
.TH "H2LOAD" "1" "January 10, 2015" "0.7.1-DEV" "nghttp2"
.SH NAME
h2load \- HTTP/2 benchmarking tool
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.B h2load
[\fI\,OPTIONS\/\fR]... [\fI\,URI\/\fR]...
.sp
\fBh2load\fP [OPTIONS]... [URI]...
.SH DESCRIPTION
.sp
benchmarking tool for HTTP/2 and SPDY server
.INDENT 0.0
.TP
<URI>
.B <URI>
Specify URI to access. Multiple URIs can be
specified. URIs are used in this order for each
client. All URIs are used, then first URI is
used and then 2nd URI, and so on. The scheme,
host and port in the subsequent URIs, if present,
are ignored. Those in the first URI are used
solely.
.SH OPTIONS
.HP
\fB\-n\fR, \fB\-\-requests=\fR<N> Number of requests. Default: 1
.UNINDENT
.SH OPTIONS:
.INDENT 0.0
.TP
\fB\-c\fR, \fB\-\-clients=\fR<N>
Number of concurrent clients. Default: 1
.B \-n, \-\-requests=<N>
Number of requests.
.sp
Default: \fB1\fP
.UNINDENT
.INDENT 0.0
.TP
\fB\-t\fR, \fB\-\-threads=\fR<N>
Number of native threads. Default: 1
.B \-c, \-\-clients=<N>
Number of concurrent clients.
.sp
Default: \fB1\fP
.UNINDENT
.INDENT 0.0
.TP
\fB\-i\fR, \fB\-\-input\-file=\fR<FILE>
.B \-t, \-\-threads=<N>
Number of native threads.
.sp
Default: \fB1\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-i, \-\-input\-file=<FILE>
Path of a file with multiple URIs are seperated
by EOLs. This option will disable URIs getting
from command\-line. If '\-' is given as <FILE>,
from command\-line. If \(aq\-\(aq is given as <FILE>,
URIs will be read from stdin. URIs are used in
this order for each client. All URIs are used,
then first URI is used and then 2nd URI, and so
on. The scheme, host and port in the subsequent
URIs, if present, are ignored. Those in the
first URI are used solely.
.UNINDENT
.INDENT 0.0
.TP
\fB\-m\fR, \fB\-\-max\-concurrent\-streams=\fR(auto|<N>)
.B \-m, \-\-max\-concurrent\-streams=(auto|<N>)
Max concurrent streams to issue per session. If
"auto" is given, the number of given URIs is
used. Default: auto
used.
.sp
Default: \fBauto\fP
.UNINDENT
.INDENT 0.0
.TP
\fB\-w\fR, \fB\-\-window\-bits=\fR<N>
.B \-w, \-\-window\-bits=<N>
Sets the stream level initial window size to
(2**<N>)\-1. For SPDY, 2**<N> is used instead.
.UNINDENT
.INDENT 0.0
.TP
\fB\-W\fR, \fB\-\-connection\-window\-bits=\fR<N>
.B \-W, \-\-connection\-window\-bits=<N>
Sets the connection level initial window size to
(2**<N>)\-1. For SPDY, if <N> is strictly less
than 16, this option is ignored. Otherwise
2**<N> is used for SPDY.
.UNINDENT
.INDENT 0.0
.TP
\fB\-H\fR, \fB\-\-header=\fR<HEADER>
.B \-H, \-\-header=<HEADER>
Add/Override a header to the requests.
.UNINDENT
.INDENT 0.0
.TP
\fB\-p\fR, \fB\-\-no\-tls\-proto=\fR<PROTOID>
.B \-p, \-\-no\-tls\-proto=<PROTOID>
Specify ALPN identifier of the protocol to be
used when accessing http URI without SSL/TLS.
Available protocols: spdy/2, spdy/3, spdy/3.1 and
h2c\-14
Default: h2c\-14
.sp
Default: \fBh2c\-14\fP
.UNINDENT
.INDENT 0.0
.TP
\fB\-v\fR, \fB\-\-verbose\fR
.B \-v, \-\-verbose
Output debug information.
.UNINDENT
.INDENT 0.0
.TP
\fB\-\-version\fR
.B \-\-version
Display version information and exit.
.UNINDENT
.INDENT 0.0
.TP
\fB\-h\fR, \fB\-\-help\fR
.B \-h, \-\-help
Display this help and exit.
.SH "SEE ALSO"

nghttp(1), nghttpd(1), nghttpx(1)
.UNINDENT
.SH SEE ALSO
.sp
\fInghttp(1)\fP, \fInghttpd(1)\fP, \fInghttpx(1)\fP
.SH AUTHOR
Tatsuhiro Tsujikawa
.SH COPYRIGHT
2012, 2014, Tatsuhiro Tsujikawa
.\" Generated by docutils manpage writer.
.
53 changes: 23 additions & 30 deletions doc/h2load.1.rst
Original file line number Diff line number Diff line change
@@ -1,23 +1,18 @@
.. DO NOT MODIFY THIS FILE! It was generated by man2rst.py
.. program:: h2load

h2load(1)
=========

NAME
----
h2load - HTTP/2 benchmarking tool

SYNOPSIS
--------

**h2load** [OPTIONS]... [URI]...

DESCRIPTION
-----------

benchmarking tool for HTTP/2 and SPDY server

.. option:: URI
.. describe:: <URI>

Specify URI to access. Multiple URIs can be
specified. URIs are used in this order for each
Expand All @@ -27,26 +22,29 @@ benchmarking tool for HTTP/2 and SPDY server
are ignored. Those in the first URI are used
solely.

OPTIONS
-------
OPTIONS:
--------

.. option:: -n, --requests=<N>

Number of requests. Default: 1
Number of requests.

Default: ``1``

.. option:: -c, --clients=<N>


Number of concurrent clients. Default: 1
Number of concurrent clients.

Default: ``1``

.. option:: -t, --threads=<N>


Number of native threads. Default: 1
Number of native threads.

Default: ``1``

.. option:: -i, --input-file=<FILE>


Path of a file with multiple URIs are seperated
by EOLs. This option will disable URIs getting
from command-line. If '-' is given as <FILE>,
Expand All @@ -59,55 +57,50 @@ OPTIONS

.. option:: -m, --max-concurrent-streams=(auto|<N>)


Max concurrent streams to issue per session. If
"auto" is given, the number of given URIs is
used. Default: auto
used.

Default: ``auto``

.. option:: -w, --window-bits=<N>


Sets the stream level initial window size to
(2\*\*<N>)-1. For SPDY, 2\*\*<N> is used instead.
(2**<N>)-1. For SPDY, 2\*\*<N> is used instead.

.. option:: -W, --connection-window-bits=<N>


Sets the connection level initial window size to
(2\*\*<N>)-1. For SPDY, if <N> is strictly less
(2**<N>)-1. For SPDY, if <N> is strictly less
than 16, this option is ignored. Otherwise
2\*\*<N> is used for SPDY.
2**<N> is used for SPDY.

.. option:: -H, --header=<HEADER>


Add/Override a header to the requests.

.. option:: -p, --no-tls-proto=<PROTOID>


Specify ALPN identifier of the protocol to be
used when accessing http URI without SSL/TLS.
Available protocols: spdy/2, spdy/3, spdy/3.1 and
h2c-14
Default: h2c-14

Default: ``h2c-14``

.. option:: -v, --verbose


Output debug information.

.. option:: --version


Display version information and exit.

.. option:: -h, --help


Display this help and exit.

SEE ALSO
--------

nghttp(1), nghttpd(1), nghttpx(1)
:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`nghttpx(1)`
3 changes: 0 additions & 3 deletions doc/h2load.h2m

This file was deleted.

4 changes: 4 additions & 0 deletions doc/h2load.h2r
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
SEE ALSO
--------

:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`nghttpx(1)`
Loading

0 comments on commit a3dcf1e

Please sign in to comment.