diff --git a/doc/Makefile.am b/doc/Makefile.am index 4f7c743e..a8b3032d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -23,10 +23,109 @@ 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 = \ mkapiref.py \ README.rst \ - apiref-header.rst \ + programmers-guide.rst \ + $(APIDOCS) \ nghttp.1.rst \ nghttpd.1.rst \ nghttpx.1.rst \ @@ -102,10 +201,14 @@ help: apiref.rst: $(top_builddir)/lib/includes/nghttp2/nghttp2ver.h \ $(top_builddir)/lib/includes/nghttp2/nghttp2.h $(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: - -rm apiref.rst + -rm $(APIDOCS) -rm -rf $(BUILDDIR)/* html-local: apiref.rst diff --git a/doc/mkapiref.py b/doc/mkapiref.py index 1d55242a..16382d49 100755 --- a/doc/mkapiref.py +++ b/doc/mkapiref.py @@ -24,19 +24,21 @@ # Generates API reference from C source code. from __future__ import print_function # At least python 2.6 is required -import re, sys, argparse +import re, sys, argparse, os.path class FunctionDoc: def __init__(self, name, content, domain): self.name = name self.content = content self.domain = domain + if self.domain == 'function': + self.funcname = re.search(r'(nghttp2_[^ )]+)\(', self.name).group(1) def write(self, out): - print('''.. {}:: {}'''.format(self.domain, self.name)) - print('') + out.write('.. {}:: {}\n'.format(self.domain, self.name)) + out.write('\n') for line in self.content: - print(' {}'.format(line)) + out.write(' {}\n'.format(line)) class StructDoc: def __init__(self, name, content, members, member_domain): @@ -47,17 +49,17 @@ class StructDoc: def write(self, out): if self.name: - print('''.. type:: {}'''.format(self.name)) - print('') + out.write('.. type:: {}\n'.format(self.name)) + out.write('\n') for line in self.content: - print(' {}'.format(line)) - print('') + out.write(' {}\n'.format(line)) + out.write('\n') for name, content in self.members: - print(''' .. {}:: {}'''.format(self.member_domain, name)) - print('') + out.write(' .. {}:: {}\n'.format(self.member_domain, name)) + out.write('\n') for line in content: - print(''' {}'''.format(line)) - print('') + out.write(' {}\n'.format(line)) + out.write('\n') class MacroDoc: def __init__(self, name, content): @@ -65,10 +67,10 @@ class MacroDoc: self.content = content def write(self, out): - print('''.. macro:: {}'''.format(self.name)) - print('') + out.write('''.. macro:: {}\n'''.format(self.name)) + out.write('\n') for line in self.content: - print(' {}'.format(line)) + out.write(' {}\n'.format(line)) def make_api_ref(infiles): macros = [] @@ -93,19 +95,65 @@ def make_api_ref(infiles): enums.append(process_enum(infile)) elif doctype == '@macro': macros.append(process_macro(infile)) + return macros, enums, types, functions + alldocs = [('Macros', macros), ('Enums', enums), ('Types (structs, unions and typedefs)', types), ('Functions', functions)] - for title, docs in alldocs: - if not docs: - continue - print(title) - print('-'*len(title)) - for doc in docs: - doc.write(sys.stdout) - print('') - print('') + +def output( + indexfile, macrosfile, enumsfile, typesfile, funcsdir, + macros, enums, types, functions): + indexfile.write(''' +API Reference +============= + +.. 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 * + +'''.format(funcname=doc.funcname, secul='='*len(doc.funcname))) + doc.write(f) def process_macro(infile): content = read_content(infile) @@ -199,12 +247,30 @@ def transform_content(content): if __name__ == '__main__': parser = argparse.ArgumentParser(description="Generate API reference") - parser.add_argument('--header', type=argparse.FileType('r'), - help='header inserted at the top of the page') + parser.add_argument('index', type=argparse.FileType('w'), + 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'), help='source file') args = parser.parse_args() - if args.header: - print(args.header.read()) + macros = [] + enums = [] + types = [] + funcs = [] 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) diff --git a/doc/apiref-header.rst b/doc/programmers-guide.rst similarity index 98% rename from doc/apiref-header.rst rename to doc/programmers-guide.rst index 259f01c1..c67c09a3 100644 --- a/doc/apiref-header.rst +++ b/doc/programmers-guide.rst @@ -1,5 +1,5 @@ -API Reference -============= +Programmers' Guide +================== 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 `nghttp2_option_set_recv_client_preface()` is not used. +.. _http-messaging: + HTTP Messaging -------------- diff --git a/doc/sources/index.rst b/doc/sources/index.rst index 1c583a7f..ddd47af0 100644 --- a/doc/sources/index.rst +++ b/doc/sources/index.rst @@ -28,6 +28,7 @@ Contents: h2load.1 nghttpx-howto h2load-howto + programmers-guide apiref libnghttp2_asio python-apiref diff --git a/lib/includes/nghttp2/nghttp2.h b/lib/includes/nghttp2/nghttp2.h index 490ffa8a..4560985a 100644 --- a/lib/includes/nghttp2/nghttp2.h +++ b/lib/includes/nghttp2/nghttp2.h @@ -1492,7 +1492,7 @@ typedef int (*nghttp2_on_begin_headers_callback)(nghttp2_session *session, * and the |value| using `nghttp2_check_header_name()` and * `nghttp2_check_header_value()`. In addition to this, nghttp2 * 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 * :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 * described in `HTTP/2 specification, section 8 * `_. - * See `HTTP Messaging`_ section for details. For those applications - * who use nghttp2 library as non-HTTP use, give nonzero to |val| to - * disable this enforcement. + * See :ref:`http-messaging` section for details. For those + * applications who use nghttp2 library as non-HTTP use, give nonzero + * to |val| to disable this enforcement. */ NGHTTP2_EXTERN void nghttp2_option_set_no_http_messaging(nghttp2_option *option, int val);