Commit 56bf7502 authored by Rahix's avatar Rahix
Browse files

chore(docs): Upgrade hawkmoth to version 0.7.0

Update vendored hawkmoth sources to commit upstream
69cde0b2c5315e46bf431a4c7c8b92cf47a544a6.
parent 425c08a6
......@@ -15,15 +15,6 @@ sys.path.insert(0, os.path.abspath("./"))
logger = sphinx.util.logging.getLogger("card10/conf.py")
# Hawkmoth does not yet support Sphinx 3
#
# See https://github.com/jnikula/hawkmoth/issues/17
if sphinx.version_info[0] > 2:
logger.warning(
"Sphinx versions >= 3 are not yet working properly with hawkmoth. Documentation of C items will probably be broken ..."
)
# -- Project information -----------------------------------------------------
project = "card10-firmware"
......
......@@ -40,9 +40,9 @@ to any symbols.
Documentation
-------------
Documentation on how to configure Hawkmoth and write documentation comments,
with examples, is available in the ``doc`` directory in the source tree,
obviously in Sphinx format and using the directive extension. Pre-built
Documentation on how to install and configure Hawkmoth, and write documentation
comments, with examples, is available in the ``doc`` directory in the source
tree, obviously in Sphinx format and using the directive extension. Pre-built
documentation `showcasing what Hawkmoth can do`_ is available at `Read the
Docs`_.
......@@ -58,11 +58,8 @@ You can install Hawkmoth from PyPI_ with::
pip install hawkmoth
You'll additionally need to install Clang and Python 3 bindings for it through
your distro's package manager; they are not available via PyPI. You may also
need to set ``LD_LIBRARY_PATH`` so that the Clang library can be found. For
example::
export LD_LIBRARY_PATH=$(llvm-config --libdir)
your distro's package manager; they are not available via PyPI. For further
details, see the documentation.
Alternatively, installation packages are available for:
......@@ -93,7 +90,7 @@ Dependencies
------------
- Python 3.4
- Sphinx 1.8
- Sphinx 3
- Clang 6.0
- Python 3 Bindings for Clang 6.0
- sphinx-testing 1.0.0 (for development)
......
......@@ -52,7 +52,10 @@ class CAutoDocDirective(Directive):
env = self.state.document.settings.env
for (severity, filename, lineno, msg) in errors:
toprint = '{}:{}: {}'.format(filename, lineno, msg)
if filename:
toprint = '{}:{}: {}'.format(filename, lineno, msg)
else:
toprint = '{}'.format(msg)
if severity.value <= env.app.verbosity:
self.logger.log(self._log_lvl[severity], toprint,
......@@ -109,7 +112,7 @@ class CAutoDocDirective(Directive):
return node.children
def setup(app):
app.require_sphinx('1.8')
app.require_sphinx('3.0')
app.add_config_value('cautodoc_root', app.confdir, 'env')
app.add_config_value('cautodoc_compat', None, 'env')
app.add_config_value('cautodoc_clang', None, 'env')
......
......@@ -39,7 +39,10 @@ def main():
print(doc)
for (severity, filename, lineno, msg) in errors:
print('{}: {}:{}: {}'.format(severity.name,
filename, lineno, msg), file=sys.stderr)
if filename:
print('{}: {}:{}: {}'.format(severity.name,
filename, lineno, msg), file=sys.stderr)
else:
print('{}: {}'.format(severity.name, msg), file=sys.stderr)
main()
# Copyright (c) 2016-2017 Jani Nikula <jani@nikula.org>
# Copyright (c) 2018-2019 Bruno Santos <brunomanuelsantos@tecnico.ulisboa.pt>
# Copyright (c) 2018-2020 Bruno Santos <brunomanuelsantos@tecnico.ulisboa.pt>
# Licensed under the terms of BSD 2-Clause, see LICENSE for details.
"""
Documentation comment extractor
......@@ -34,6 +34,7 @@ Otherwise, documentation comments are passed through verbatim.
"""
import enum
import re
import sys
from clang.cindex import CursorKind, TypeKind
......@@ -166,8 +167,26 @@ def _recursive_parse(comments, cursor, nest, compat):
return _result(comment, cursor=cursor, fmt=fmt,
nest=nest, name=name, args=args, compat=compat)
elif cursor.kind == CursorKind.VAR_DECL:
fmt = docstr.Type.VAR
elif cursor.kind in [CursorKind.VAR_DECL, CursorKind.FIELD_DECL]:
if cursor.kind == CursorKind.VAR_DECL:
fmt = docstr.Type.VAR
else:
fmt = docstr.Type.MEMBER
# If this is an array, the dimensions should be applied to the name, not
# the type.
dims = ttype.rsplit(' ', 1)[-1]
if dims.startswith('[') and dims.endswith(']'):
ttype = ttype.rsplit(' ', 1)[0]
name = name + dims
# If this is a function pointer, or an array of function pointers, the
# name should be within the parenthesis as in (*name) or (*name[N]).
fptr_type = re.sub(r'\((\*+)(\[[^]]*\])?\)', r'(\1{}\2)'.format(name),
ttype, count=1)
if fptr_type != ttype:
name = fptr_type
ttype = ''
return _result(comment, cursor=cursor, fmt=fmt,
nest=nest, name=name, ttype=ttype, compat=compat)
......@@ -193,9 +212,15 @@ def _recursive_parse(comments, cursor, nest, compat):
# FIXME: Handle anonymous enumerators.
fmt = docstr.Type.TYPE
fmts = {CursorKind.STRUCT_DECL: docstr.Type.STRUCT,
CursorKind.UNION_DECL: docstr.Type.UNION,
CursorKind.ENUM_DECL: docstr.Type.ENUM}
fmt = fmts[cursor.kind]
# name may be empty for typedefs
result = _result(comment, cursor=cursor, fmt=fmt,
nest=nest, name=ttype, compat=compat)
nest=nest, name=name if name else ttype, compat=compat)
nest += 1
for c in cursor.get_children():
......@@ -210,12 +235,6 @@ def _recursive_parse(comments, cursor, nest, compat):
return _result(comment, cursor=cursor, fmt=fmt,
nest=nest, name=name, compat=compat)
elif cursor.kind == CursorKind.FIELD_DECL:
fmt = docstr.Type.MEMBER
return _result(comment, cursor=cursor, fmt=fmt,
nest=nest, name=name, ttype=ttype, compat=compat)
elif cursor.kind == CursorKind.FUNCTION_DECL:
# FIXME: check args against comment
# FIXME: children may contain extra stuff if the return type is a
......@@ -266,7 +285,8 @@ def clang_diagnostics(errors, diagnostics):
4: ErrorLevel.ERROR}
for diag in diagnostics:
errors.extend([(sev[diag.severity], diag.location.file.name,
filename = diag.location.file.name if diag.location.file else None
errors.extend([(sev[diag.severity], filename,
diag.location.line, diag.spelling)])
# return a list of (comment, metadata) tuples
......
# Copyright (c) 2016-2017 Jani Nikula <jani@nikula.org>
# Copyright (c) 2018-2019 Bruno Santos <brunomanuelsantos@tecnico.ulisboa.pt>
# Copyright (c) 2016-2020 Jani Nikula <jani@nikula.org>
# Copyright (c) 2018-2020 Bruno Santos <brunomanuelsantos@tecnico.ulisboa.pt>
# Licensed under the terms of BSD 2-Clause, see LICENSE for details.
"""
Documentation strings manipulation library
......@@ -17,6 +17,9 @@ class Type(Enum):
TEXT = auto()
VAR = auto()
TYPE = auto()
STRUCT = auto()
UNION = auto()
ENUM = auto()
ENUM_VAL = auto()
MEMBER = auto()
MACRO = auto()
......@@ -31,10 +34,13 @@ _doc_fmt = {
Type.TEXT: (0, '\n{text}\n'),
Type.VAR: (1, '\n.. c:var:: {ttype} {name}\n\n{text}\n'),
Type.TYPE: (1, '\n.. c:type:: {name}\n\n{text}\n'),
Type.ENUM_VAL: (1, '\n.. c:macro:: {name}\n\n{text}\n'),
Type.STRUCT: (1, '\n.. c:struct:: {name}\n\n{text}\n'),
Type.UNION: (1, '\n.. c:union:: {name}\n\n{text}\n'),
Type.ENUM: (1, '\n.. c:enum:: {name}\n\n{text}\n'),
Type.ENUM_VAL: (1, '\n.. c:enumerator:: {name}\n\n{text}\n'),
Type.MEMBER: (1, '\n.. c:member:: {ttype} {name}\n\n{text}\n'),
Type.MACRO: (1, '\n.. c:macro:: {name}\n\n{text}\n'),
Type.MACRO_FUNC: (1, '\n.. c:function:: {name}({args})\n\n{text}\n'),
Type.MACRO_FUNC: (1, '\n.. c:macro:: {name}({args})\n\n{text}\n'),
Type.FUNC: (1, '\n.. c:function:: {ttype} {name}({args})\n\n{text}\n')
}
......
# Copyright (c) 2021, Jani Nikula <jani@nikula.org>
# Licensed under the terms of BSD 2-Clause, see LICENSE for details.
"""
Read the Docs Helpers
=====================
Helpers for setting up and using Hawkmoth on Read the Docs.
"""
import os
import subprocess
def clang_setup(force=False):
"""Try to find and configure libclang location on RTD."""
if 'READTHEDOCS' in os.environ or force:
try:
result = subprocess.run(['llvm-config', '--libdir'],
check=True, capture_output=True, encoding='utf-8')
libdir = result.stdout.strip()
# For some reason there is no plain libclang.so symlink on RTD.
from clang.cindex import Config
Config.set_library_file(os.path.join(libdir, 'libclang.so.1'))
except Exception as e:
print(e)
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment