3bb59f00e5
Correct outdated information in the set_cookie() docstring, as well as expound on certain key points and provide references to relevant sections of RFC 6265.
67 lines
1.7 KiB
Python
67 lines
1.7 KiB
Python
# Copyright 2016 by Rackspace Hosting, Inc.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
"""RFC extension for Sphinx.
|
|
|
|
This extensions adds hyperlinking for any RFC references that are
|
|
formatted like this::
|
|
|
|
RFC 7231; Section 6.5.3
|
|
|
|
"""
|
|
|
|
import re
|
|
|
|
|
|
RFC_PATTERN = re.compile('RFC (\d{4}), Section ([\d\.]+)')
|
|
|
|
|
|
def _render_section(section_number, rfc_number):
|
|
template = '`{0} <https://tools.ietf.org/html/rfc{1}#section-{0}>`_'
|
|
return template.format(section_number, rfc_number)
|
|
|
|
|
|
def _process_line(line):
|
|
m = RFC_PATTERN.search(line)
|
|
if not m:
|
|
return line
|
|
|
|
rfc = m.group(1)
|
|
section = m.group(2)
|
|
|
|
template = (
|
|
'`RFC {rfc}, Section {section} '
|
|
'<https://tools.ietf.org/html/rfc{rfc}#section-{section}>`_'
|
|
)
|
|
|
|
rendered_text = template.format(rfc=rfc, section=section)
|
|
|
|
return line[:m.start()] + rendered_text + line[m.end():]
|
|
|
|
|
|
def _on_process_docstring(app, what, name, obj, options, lines):
|
|
"""Process the docstring for a given python object."""
|
|
|
|
if what == 'module' and name == 'falcon':
|
|
lines[:] = []
|
|
return
|
|
|
|
lines[:] = [_process_line(line) for line in lines]
|
|
|
|
|
|
def setup(app):
|
|
app.connect('autodoc-process-docstring', _on_process_docstring)
|
|
|
|
return {'parallel_read_safe': True}
|