diff options
Diffstat (limited to 'web/server/h2o/libh2o/deps/picotls/deps/cifra/doc')
4 files changed, 573 insertions, 0 deletions
diff --git a/web/server/h2o/libh2o/deps/picotls/deps/cifra/doc/Makefile b/web/server/h2o/libh2o/deps/picotls/deps/cifra/doc/Makefile new file mode 100644 index 00000000..2b7f5c03 --- /dev/null +++ b/web/server/h2o/libh2o/deps/picotls/deps/cifra/doc/Makefile @@ -0,0 +1,3 @@ +default: all +all: + sphinx-build -b html . _build diff --git a/web/server/h2o/libh2o/deps/picotls/deps/cifra/doc/build.py b/web/server/h2o/libh2o/deps/picotls/deps/cifra/doc/build.py new file mode 100644 index 00000000..0b006825 --- /dev/null +++ b/web/server/h2o/libh2o/deps/picotls/deps/cifra/doc/build.py @@ -0,0 +1,274 @@ +""" +Extracts documentation from cifra headers. + +We want to embed documentation in headers for good +locality. But want to write rst for formatting by sphinx. +This is a problem. + +'Breathe' provides a bridge between doxygen and sphinx, +but doxygen's documentation markup is pretty awful. + +Therefore, we write rst directly in C headers, and then +extract it here. The rules are: a C block comment +starting exactly '/* .. ' is dedented, and then included +verbatim. The convention is that the documentation +preceeds the C declarations they apply to, and that struct +members are documented before the struct they are contained +within. eg: + +/* .. c:function:: int foo(int bar) + * Foos a bar, returning the foo coefficient. + */ +int foo(int bar); + +/* .. c:type:: thing + * Container for things. + * + * .. c:member:: int thing.foo + * Count of foos. + * + * .. c:member:: int thing.bar + * Count of bars. + */ +typedef struct +{ + int foo; + int bar; +} thing; + +As a special effect, the following tokens are replaced +in the comments: + + - $DECL: the immediately following function declaration +""" + +import glob +import re +import StringIO + +# We know which headers constitute the external interface. +EXTERNAL = """ +aes +cf_config +chash +hmac +modes +pbkdf2 +prp +salsa20 +sha1 +sha2 +sha3 +norx +poly1305 +chacha20poly1305 +drbg +""".split() + +# Basic idea of a C identifier +C_IDENTIFIER = '[a-zA-Z_][a-zA-Z0-9_]+' + +DECL_RE = re.compile(r'^\s*(.+?' + C_IDENTIFIER + '\(.+?\));', re.MULTILINE | re.DOTALL) +COMMENT_RE = re.compile(r'^\s*\/\* (\.\..*?) \*\/$', re.MULTILINE | re.DOTALL) +INTRO_RE = re.compile(r'^\s*\/\*\*(.*?)\*\/$', re.MULTILINE | re.DOTALL) +NEW_SECTION_RE = re.compile(r'^..+\n(==+|--+)$', re.MULTILINE) + +class section(object): + def __init__(self): + self.intro = [] + self.macros = [] + self.types = [] + self.functions = [] + self.values = [] + + def __repr__(self): + return repr(self.format()[:30]) + + def __str__(self): + return repr(self.format()[:30]) + + def format(self): + f = StringIO.StringIO() + + def emit(title, section): + if len(section) == 0: + return + + if title: + print >>f, title + print >>f, '*' * len(title) + print >>f + + for s in section: + print >>f, s.getvalue() + + emit(None, self.intro) + emit('Macros', self.macros) + emit('Types', self.types) + emit('Functions', self.functions) + emit('Values', self.values) + + return f.getvalue() + + def is_empty(self): + items = len(self.intro) + len(self.macros) + len(self.types) + \ + len(self.functions) + len(self.values) + return 0 == items + + def add_item(self, sec): + f = StringIO.StringIO() + sec.append(f) + return f + +def massage_decl(decl): + """ + Tart-up a C function declaration: remove storage qualifiers, + smush onto one line, escape asterisks. + """ + for storage in 'extern static inline'.split(): + decl = decl.replace(storage + ' ', '') + + fixed_lines = ' '.join(line.strip() for line in decl.splitlines()) + + return fixed_lines.replace('*', '\\*') + +def replace_decl(comment, comment_match, header): + if '$DECL' not in comment: + return comment + + start = comment_match.end(0) + 1 + decl_match = DECL_RE.match(header, start) + + if decl_match is None: + print 'Cause:', comment + print 'Trailer:', header[start:start+60] + raise IOError('$DECL present but cannot find following DECL') + + decl = decl_match.group(1) + decl = massage_decl(decl) + return comment.replace('$DECL', decl) + +def decomment(lines): + for i in range(len(lines)): + if lines[i].startswith(' *'): + lines[i] = lines[i][3:] + lines[i] = lines[i].strip() + +def drop_empty_prefix(lines): + while len(lines) and lines[0] == '': + lines.pop(0) + +def starts_new_section(lines): + txt = '\n'.join(lines) + r = NEW_SECTION_RE.search(txt) is not None + return r + +def process(header, rst): + """ + Converts a header into restructured text. + + header is a file-like opened to read the header. + rst is a file-like opened to write the rst results. + """ + + hh = header.read() + + # Collect definitions into sections + sec = None + all_sections = [] + intro, macros, types, functions, values = [], [], [], [], [] + + def add_section(): + if sec and not sec.is_empty(): + all_sections.append(sec) + return section() + + sec = add_section() + + offs = 0 + + while True: + intro_match = INTRO_RE.search(hh, offs) + comment_match = COMMENT_RE.search(hh, offs) + + if intro_match is None and comment_match is None: + break + + # process earliest occuring + if intro_match is not None and (comment_match is None or intro_match.start(0) < comment_match.start(0)): + txt = intro_match.group(1) + + lines = txt.splitlines() + decomment(lines) + drop_empty_prefix(lines) + + if starts_new_section(lines): + sec = add_section() + + outf = sec.add_item(sec.intro) + + for l in lines: + print >>outf, l + offs = intro_match.end(0) + 1 + continue + + if comment_match is not None and (intro_match is None or comment_match.start(0) < intro_match.start(0)): + txt = comment_match.group(1) + + # work out which section this goes into + outf = None + if '.. c:macro::' in txt: + outf = sec.add_item(sec.macros) + elif '.. c:type::' in txt: + outf = sec.add_item(sec.types) + elif '.. c:var::' in txt: + outf = sec.add_item(sec.values) + elif '.. c:function::' in txt: + outf = sec.add_item(sec.functions) + elif '.. c:member::' in txt: + if len(types) == 0: + raise IOError('c:member must come after a c:type') + outf = types[-1] + else: + raise IOError('Cannot categorise item: ' + txt) + + # expand $DECL + txt = replace_decl(txt, comment_match, hh) + + # decomment lines + lines = txt.splitlines() + decomment(lines) + + # domain lines are unindented + while lines and lines[0].startswith('.. '): + print >>outf, lines.pop(0) + print >>outf + + # empty prefix lines are stripped + drop_empty_prefix(lines) + + # other lines are indented + for line in lines: + if len(line): + line = ' ' + line + print >>outf, line + + offs = comment_match.end(0) + 1 + continue + + add_section() + + for sec in all_sections: + rst.write(sec.format()) + +def run(): + for fn in EXTERNAL: + print '** build', fn + header = '../src/' + fn + '.h' + rst = fn + '.rst' + with open(header, 'r') as fh: + with open(rst, 'w') as fr: + process(fh, fr) + +if __name__ == '__main__': + run() diff --git a/web/server/h2o/libh2o/deps/picotls/deps/cifra/doc/conf.py b/web/server/h2o/libh2o/deps/picotls/deps/cifra/doc/conf.py new file mode 100644 index 00000000..8354354c --- /dev/null +++ b/web/server/h2o/libh2o/deps/picotls/deps/cifra/doc/conf.py @@ -0,0 +1,263 @@ +# -*- coding: utf-8 -*- +# +# Cifra documentation build configuration file, created by +# sphinx-quickstart on Sat Feb 21 18:02:37 2015. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('.')) + +import build +build.run() + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.mathjax', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Cifra' +copyright = u'2015, Joseph Birr-Pixton' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Cifradoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'Cifra.tex', u'Cifra Documentation', + u'Joseph Birr-Pixton', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'cifra', u'Cifra Documentation', + [u'Joseph Birr-Pixton'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'Cifra', u'Cifra Documentation', + u'Joseph Birr-Pixton', 'Cifra', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/web/server/h2o/libh2o/deps/picotls/deps/cifra/doc/index.rst b/web/server/h2o/libh2o/deps/picotls/deps/cifra/doc/index.rst new file mode 100644 index 00000000..e853de4a --- /dev/null +++ b/web/server/h2o/libh2o/deps/picotls/deps/cifra/doc/index.rst @@ -0,0 +1,33 @@ +.. Cifra documentation master file, created by + sphinx-quickstart on Sat Feb 21 18:02:37 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Cifra's documentation! +================================= + +Contents: + +.. toctree:: + :maxdepth: 2 + + cf_config + prp + chash + aes + norx + salsa20 + modes + hmac + poly1305 + chacha20poly1305 + pbkdf2 + sha1 + sha2 + sha3 + drbg + +Index +----- +* :ref:`genindex` + |