doc: Split API reference into smaller fine grained files

Previously API reference is gigantic one rst file and it is a bit hard
to use, especially when browsing similar functions.  This commit
splits API reference into smaller fine grained files.  The macros,
enums, types are now in its own file.  Each API function has its own
file now.  API reference doc is now index to above documentation
files.  The apiref-header.rst is renamed as programmers-guide.rst and
becomes standalone document.
This commit is contained in:
Tatsuhiro Tsujikawa 2015-04-01 01:13:10 +09:00
parent 363914c3f7
commit 87029e05af
5 changed files with 210 additions and 38 deletions

View File

@ -23,10 +23,109 @@
man_MANS = nghttp.1 nghttpd.1 nghttpx.1 h2load.1 man_MANS = nghttp.1 nghttpd.1 nghttpx.1 h2load.1
APIDOCS= \
apiref.rst \
macros.rst \
enums.rst \
types.rst \
nghttp2_check_header_name.rst \
nghttp2_check_header_value.rst \
nghttp2_hd_deflate_bound.rst \
nghttp2_hd_deflate_change_table_size.rst \
nghttp2_hd_deflate_del.rst \
nghttp2_hd_deflate_hd.rst \
nghttp2_hd_deflate_new.rst \
nghttp2_hd_deflate_new2.rst \
nghttp2_hd_inflate_change_table_size.rst \
nghttp2_hd_inflate_del.rst \
nghttp2_hd_inflate_end_headers.rst \
nghttp2_hd_inflate_hd.rst \
nghttp2_hd_inflate_new.rst \
nghttp2_hd_inflate_new2.rst \
nghttp2_is_fatal.rst \
nghttp2_nv_compare_name.rst \
nghttp2_option_del.rst \
nghttp2_option_new.rst \
nghttp2_option_set_no_auto_window_update.rst \
nghttp2_option_set_no_http_messaging.rst \
nghttp2_option_set_peer_max_concurrent_streams.rst \
nghttp2_option_set_recv_client_preface.rst \
nghttp2_pack_settings_payload.rst \
nghttp2_priority_spec_check_default.rst \
nghttp2_priority_spec_default_init.rst \
nghttp2_priority_spec_init.rst \
nghttp2_select_next_protocol.rst \
nghttp2_session_callbacks_del.rst \
nghttp2_session_callbacks_new.rst \
nghttp2_session_callbacks_set_before_frame_send_callback.rst \
nghttp2_session_callbacks_set_data_source_read_length_callback.rst \
nghttp2_session_callbacks_set_on_begin_frame_callback.rst \
nghttp2_session_callbacks_set_on_begin_headers_callback.rst \
nghttp2_session_callbacks_set_on_data_chunk_recv_callback.rst \
nghttp2_session_callbacks_set_on_frame_not_send_callback.rst \
nghttp2_session_callbacks_set_on_frame_recv_callback.rst \
nghttp2_session_callbacks_set_on_frame_send_callback.rst \
nghttp2_session_callbacks_set_on_header_callback.rst \
nghttp2_session_callbacks_set_on_invalid_frame_recv_callback.rst \
nghttp2_session_callbacks_set_on_stream_close_callback.rst \
nghttp2_session_callbacks_set_recv_callback.rst \
nghttp2_session_callbacks_set_select_padding_callback.rst \
nghttp2_session_callbacks_set_send_callback.rst \
nghttp2_session_client_new.rst \
nghttp2_session_client_new2.rst \
nghttp2_session_client_new3.rst \
nghttp2_session_consume.rst \
nghttp2_session_del.rst \
nghttp2_session_get_effective_local_window_size.rst \
nghttp2_session_get_effective_recv_data_length.rst \
nghttp2_session_get_last_proc_stream_id.rst \
nghttp2_session_get_next_stream_id.rst \
nghttp2_session_get_outbound_queue_size.rst \
nghttp2_session_get_remote_settings.rst \
nghttp2_session_get_remote_window_size.rst \
nghttp2_session_get_stream_effective_local_window_size.rst \
nghttp2_session_get_stream_effective_recv_data_length.rst \
nghttp2_session_get_stream_local_close.rst \
nghttp2_session_get_stream_remote_close.rst \
nghttp2_session_get_stream_remote_window_size.rst \
nghttp2_session_get_stream_user_data.rst \
nghttp2_session_mem_recv.rst \
nghttp2_session_mem_send.rst \
nghttp2_session_recv.rst \
nghttp2_session_resume_data.rst \
nghttp2_session_send.rst \
nghttp2_session_server_new.rst \
nghttp2_session_server_new2.rst \
nghttp2_session_server_new3.rst \
nghttp2_session_set_next_stream_id.rst \
nghttp2_session_set_stream_user_data.rst \
nghttp2_session_terminate_session.rst \
nghttp2_session_terminate_session2.rst \
nghttp2_session_upgrade.rst \
nghttp2_session_want_read.rst \
nghttp2_session_want_write.rst \
nghttp2_strerror.rst \
nghttp2_submit_altsvc.rst \
nghttp2_submit_data.rst \
nghttp2_submit_goaway.rst \
nghttp2_submit_headers.rst \
nghttp2_submit_ping.rst \
nghttp2_submit_priority.rst \
nghttp2_submit_push_promise.rst \
nghttp2_submit_request.rst \
nghttp2_submit_response.rst \
nghttp2_submit_rst_stream.rst \
nghttp2_submit_settings.rst \
nghttp2_submit_shutdown_notice.rst \
nghttp2_submit_trailer.rst \
nghttp2_submit_window_update.rst \
nghttp2_version.rst
EXTRA_DIST = \ EXTRA_DIST = \
mkapiref.py \ mkapiref.py \
README.rst \ README.rst \
apiref-header.rst \ programmers-guide.rst \
$(APIDOCS) \
nghttp.1.rst \ nghttp.1.rst \
nghttpd.1.rst \ nghttpd.1.rst \
nghttpx.1.rst \ nghttpx.1.rst \
@ -102,10 +201,14 @@ help:
apiref.rst: $(top_builddir)/lib/includes/nghttp2/nghttp2ver.h \ apiref.rst: $(top_builddir)/lib/includes/nghttp2/nghttp2ver.h \
$(top_builddir)/lib/includes/nghttp2/nghttp2.h $(top_builddir)/lib/includes/nghttp2/nghttp2.h
$(PYTHON) $(top_srcdir)/doc/mkapiref.py \ $(PYTHON) $(top_srcdir)/doc/mkapiref.py \
--header $(top_srcdir)/doc/apiref-header.rst $^ > $@ $@ \
$(top_builddir)/doc/macros.rst \
$(top_builddir)/doc/enums.rst \
$(top_builddir)/doc/types.rst \
$(top_builddir)/doc/ $^
clean-local: clean-local:
-rm apiref.rst -rm $(APIDOCS)
-rm -rf $(BUILDDIR)/* -rm -rf $(BUILDDIR)/*
html-local: apiref.rst html-local: apiref.rst

View File

@ -24,19 +24,21 @@
# Generates API reference from C source code. # Generates API reference from C source code.
from __future__ import print_function # At least python 2.6 is required from __future__ import print_function # At least python 2.6 is required
import re, sys, argparse import re, sys, argparse, os.path
class FunctionDoc: class FunctionDoc:
def __init__(self, name, content, domain): def __init__(self, name, content, domain):
self.name = name self.name = name
self.content = content self.content = content
self.domain = domain self.domain = domain
if self.domain == 'function':
self.funcname = re.search(r'(nghttp2_[^ )]+)\(', self.name).group(1)
def write(self, out): def write(self, out):
print('''.. {}:: {}'''.format(self.domain, self.name)) out.write('.. {}:: {}\n'.format(self.domain, self.name))
print('') out.write('\n')
for line in self.content: for line in self.content:
print(' {}'.format(line)) out.write(' {}\n'.format(line))
class StructDoc: class StructDoc:
def __init__(self, name, content, members, member_domain): def __init__(self, name, content, members, member_domain):
@ -47,17 +49,17 @@ class StructDoc:
def write(self, out): def write(self, out):
if self.name: if self.name:
print('''.. type:: {}'''.format(self.name)) out.write('.. type:: {}\n'.format(self.name))
print('') out.write('\n')
for line in self.content: for line in self.content:
print(' {}'.format(line)) out.write(' {}\n'.format(line))
print('') out.write('\n')
for name, content in self.members: for name, content in self.members:
print(''' .. {}:: {}'''.format(self.member_domain, name)) out.write(' .. {}:: {}\n'.format(self.member_domain, name))
print('') out.write('\n')
for line in content: for line in content:
print(''' {}'''.format(line)) out.write(' {}\n'.format(line))
print('') out.write('\n')
class MacroDoc: class MacroDoc:
def __init__(self, name, content): def __init__(self, name, content):
@ -65,10 +67,10 @@ class MacroDoc:
self.content = content self.content = content
def write(self, out): def write(self, out):
print('''.. macro:: {}'''.format(self.name)) out.write('''.. macro:: {}\n'''.format(self.name))
print('') out.write('\n')
for line in self.content: for line in self.content:
print(' {}'.format(line)) out.write(' {}\n'.format(line))
def make_api_ref(infiles): def make_api_ref(infiles):
macros = [] macros = []
@ -93,19 +95,65 @@ def make_api_ref(infiles):
enums.append(process_enum(infile)) enums.append(process_enum(infile))
elif doctype == '@macro': elif doctype == '@macro':
macros.append(process_macro(infile)) macros.append(process_macro(infile))
return macros, enums, types, functions
alldocs = [('Macros', macros), alldocs = [('Macros', macros),
('Enums', enums), ('Enums', enums),
('Types (structs, unions and typedefs)', types), ('Types (structs, unions and typedefs)', types),
('Functions', functions)] ('Functions', functions)]
for title, docs in alldocs:
if not docs: def output(
continue indexfile, macrosfile, enumsfile, typesfile, funcsdir,
print(title) macros, enums, types, functions):
print('-'*len(title)) indexfile.write('''
for doc in docs: API Reference
doc.write(sys.stdout) =============
print('')
print('') .. toctree::
:maxdepth: 1
macros
enums
types
''')
for doc in functions:
indexfile.write(' {}\n'.format(doc.funcname))
macrosfile.write('''
Macros
======
''')
for doc in macros:
doc.write(macrosfile)
enumsfile.write('''
Enums
=====
''')
for doc in enums:
doc.write(enumsfile)
typesfile.write('''
Types (structs, unions and typedefs)
====================================
''')
for doc in types:
doc.write(typesfile)
for doc in functions:
with open(os.path.join(funcsdir, doc.funcname + '.rst'), 'w') as f:
f.write('''
{funcname}
{secul}
Synopsis
--------
*#include <nghttp2/nghttp2.h>*
'''.format(funcname=doc.funcname, secul='='*len(doc.funcname)))
doc.write(f)
def process_macro(infile): def process_macro(infile):
content = read_content(infile) content = read_content(infile)
@ -199,12 +247,30 @@ def transform_content(content):
if __name__ == '__main__': if __name__ == '__main__':
parser = argparse.ArgumentParser(description="Generate API reference") parser = argparse.ArgumentParser(description="Generate API reference")
parser.add_argument('--header', type=argparse.FileType('r'), parser.add_argument('index', type=argparse.FileType('w'),
help='header inserted at the top of the page') help='index output file')
parser.add_argument('macros', type=argparse.FileType('w'),
help='macros section output file. The filename should be macros.rst')
parser.add_argument('enums', type=argparse.FileType('w'),
help='enums section output file. The filename should be enums.rst')
parser.add_argument('types', type=argparse.FileType('w'),
help='types section output file. The filename should be types.rst')
parser.add_argument('funcsdir',
help='functions doc output dir')
parser.add_argument('files', nargs='+', type=argparse.FileType('r'), parser.add_argument('files', nargs='+', type=argparse.FileType('r'),
help='source file') help='source file')
args = parser.parse_args() args = parser.parse_args()
if args.header: macros = []
print(args.header.read()) enums = []
types = []
funcs = []
for infile in args.files: for infile in args.files:
make_api_ref(args.files) m, e, t, f = make_api_ref(args.files)
macros.extend(m)
enums.extend(e)
types.extend(t)
funcs.extend(f)
funcs.sort(key=lambda x: x.funcname)
output(
args.index, args.macros, args.enums, args.types, args.funcsdir,
macros, enums, types, funcs)

View File

@ -1,5 +1,5 @@
API Reference Programmers' Guide
============= ==================
Includes Includes
-------- --------
@ -32,6 +32,8 @@ value. The applications are responsible to receive it before calling
these functions if :type:`nghttp2_session` is configured as server and these functions if :type:`nghttp2_session` is configured as server and
`nghttp2_option_set_recv_client_preface()` is not used. `nghttp2_option_set_recv_client_preface()` is not used.
.. _http-messaging:
HTTP Messaging HTTP Messaging
-------------- --------------

View File

@ -28,6 +28,7 @@ Contents:
h2load.1 h2load.1
nghttpx-howto nghttpx-howto
h2load-howto h2load-howto
programmers-guide
apiref apiref
libnghttp2_asio libnghttp2_asio
python-apiref python-apiref

View File

@ -1492,7 +1492,7 @@ typedef int (*nghttp2_on_begin_headers_callback)(nghttp2_session *session,
* and the |value| using `nghttp2_check_header_name()` and * and the |value| using `nghttp2_check_header_name()` and
* `nghttp2_check_header_value()`. In addition to this, nghttp2 * `nghttp2_check_header_value()`. In addition to this, nghttp2
* performs vaidation based on HTTP Messaging rule, which is briefly * performs vaidation based on HTTP Messaging rule, which is briefly
* explained in `HTTP Messaging`_ section. * explained in :ref:`http-messaging` section.
* *
* If the application uses `nghttp2_session_mem_recv()`, it can return * If the application uses `nghttp2_session_mem_recv()`, it can return
* :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()` * :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`
@ -1973,9 +1973,9 @@ nghttp2_option_set_recv_client_preface(nghttp2_option *option, int val);
* By default, nghttp2 library enforces subset of HTTP Messaging rules * By default, nghttp2 library enforces subset of HTTP Messaging rules
* described in `HTTP/2 specification, section 8 * described in `HTTP/2 specification, section 8
* <https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-8>`_. * <https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-8>`_.
* See `HTTP Messaging`_ section for details. For those applications * See :ref:`http-messaging` section for details. For those
* who use nghttp2 library as non-HTTP use, give nonzero to |val| to * applications who use nghttp2 library as non-HTTP use, give nonzero
* disable this enforcement. * to |val| to disable this enforcement.
*/ */
NGHTTP2_EXTERN void nghttp2_option_set_no_http_messaging(nghttp2_option *option, NGHTTP2_EXTERN void nghttp2_option_set_no_http_messaging(nghttp2_option *option,
int val); int val);