walkero
/
nghttp2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
doc/Makefile.am
View File

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

124
doc/mkapiref.py
View File

@ -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 <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'),
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)

6
doc/apiref-header.rst → doc/programmers-guide.rst
View File

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

1
doc/sources/index.rst
View File

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

8
lib/includes/nghttp2/nghttp2.h
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
* `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
* 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);