From 87029e05af8b1ae195060a255c2c99ca5a8d9cf7 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Wed, 1 Apr 2015 01:13:10 +0900 Subject: [PATCH] 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. --- doc/Makefile.am | 109 ++++++++++++++- doc/mkapiref.py | 124 ++++++++++++++---- ...piref-header.rst => programmers-guide.rst} | 6 +- doc/sources/index.rst | 1 + lib/includes/nghttp2/nghttp2.h | 8 +- 5 files changed, 210 insertions(+), 38 deletions(-) rename doc/{apiref-header.rst => programmers-guide.rst} (98%) 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);