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

@@ -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

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))
+        out.write('.. {}:: {}\n'.format(self.domain, self.name))
-        print('')
+        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))
+            out.write('.. type:: {}\n'.format(self.name))
-            print('')
+            out.write('\n')
             for line in self.content:
-                print('    {}'.format(line))
+                out.write('    {}\n'.format(line))
-            print('')
+            out.write('\n')
             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:
-                    print('''        {}'''.format(line))
+                    out.write('        {}\n'.format(line))
-            print('')
+            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))
+        out.write('''.. macro:: {}\n'''.format(self.name))
-        print('')
+        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:
+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):
     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'),
+    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'),
                         help='source file')
     args = parser.parse_args()
-    if args.header:
+    macros = []
-        print(args.header.read())
+    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)

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
 --------------
 

doc/sources/index.rst

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

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
  * <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,
                                                          int val);