Commit 49e780a2 authored by Rahix's avatar Rahix
Browse files

Merge 'Upgrade to Sphinx 3'

See merge request !460
parents a97d113e 977c8b46
Pipeline #5182 passed with stages
in 2 minutes
......@@ -46,7 +46,7 @@ lint:
pages:
stage: deploy
# maintaned by q3k, build using docker/deploy-env
image: "derq3k/card10-deploy-env:20190806-200743Z-f95b541-dirty"
image: "registry.k0.hswaw.net/q3k/card10-deploy-env:20210403-110003Z-4d929ee0"
script:
- export LD_LIBRARY_PATH=$(llvm-config --libdir)
- echo $LD_LIBRARY_PATH
......
......@@ -17,7 +17,7 @@ If :ref:`bsec_api` is enabled the following additional estimates are available:
- Indoor air quality (IAQ estimate
- Equivalent CO2 (eCO2) estimate
Please refer to :ref:`bme680` for more information about BSEC.
Please refer to :py:mod:`bme680` for more information about BSEC.
If notifcations are enabled a measurement of all values is performed every 3 seconds. For each measurement a notification is sent for the characteristics which have notifications enabled.
......
......@@ -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"
......@@ -158,3 +149,32 @@ except ImportError as e:
def setup(app):
app.add_config_value("has_hawkmoth", has_hawkmoth, "")
app.add_directive("color-example", ColorExample)
fix_issue_8945()
def fix_issue_8945():
c_domain = __import__("sphinx.domains.c").domains.c
for kw in [
"char",
"float",
"int",
"long",
"short",
"void",
"_Bool",
"bool",
"_Complex",
"complex",
]:
c_domain._keywords.remove(kw)
def parse_xref_object(self):
name = self._parse_nested_name()
self.skip_ws()
self.skip_string("()")
# Removing this line as a hacky workaround:
# self.assert_end()
return name
c_domain.DefinitionParser.parse_xref_object = parse_xref_object
......@@ -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)
``png`` - PNG Decoder
===============
=====================
The ``png`` module provides functions to decode PNG files into raw pixel data
which can be displayed using the card10's display or its LEDs.
......
FROM ubuntu:bionic
FROM ubuntu:focal
RUN set -e -x ;\
export DEBIAN_FRONTEND=noninteractive ;\
......@@ -10,7 +10,7 @@ RUN set -e -x ;\
llvm \
python3-pip ;\
pip3 install \
clang \
clang==10.0.1 \
sphinx \
sphinx_rtd_theme ;\
rm -rf /var/lib/apt/lists
......
......@@ -1814,6 +1814,12 @@ API(API_DISP_FRAMEBUFFER, int epic_disp_framebuffer(
));
/**
* Light Sensor
* ============
*/
/**
* Set the backlight brightness.
*
......@@ -1827,12 +1833,12 @@ API(API_DISP_BACKLIGHT, int epic_disp_backlight(uint16_t brightness));
/**
* Start continuous readout of the light sensor. Will read light level
* at preconfigured interval and make it available via `epic_light_sensor_get()`.
* at preconfigured interval and make it available via :c:func:`epic_light_sensor_get`.
*
* If the continuous readout was already running, this function will silently pass.
*
*
* :return: `0` if the start was successful or a negative error value
* :return: ``0`` if the start was successful or a negative error value
* if an error occured. Possible errors:
*
* - ``-EBUSY``: The timer could not be scheduled.
......@@ -1843,7 +1849,7 @@ API(API_LIGHT_SENSOR_RUN, int epic_light_sensor_run());
* Get the last light level measured by the continuous readout.
*
* :param uint16_t* value: where the last light level should be written.
* :return: `0` if the readout was successful or a negative error
* :return: ``0`` if the readout was successful or a negative error
* value. Possible errors:
*
* - ``-ENODATA``: Continuous readout not currently running.
......@@ -1856,7 +1862,7 @@ API(API_LIGHT_SENSOR_GET, int epic_light_sensor_get(uint16_t* value));
*
* If the continuous readout wasn't running, this function will silently pass.
*
* :return: `0` if the stop was sucessful or a negative error value
* :return: ``0`` if the stop was sucessful or a negative error value
* if an error occured. Possible errors:
*
* - ``-EBUSY``: The timer stop could not be scheduled.
......@@ -2110,7 +2116,7 @@ API(API_RTC_SET_MILLISECONDS, void epic_rtc_set_milliseconds(
* Schedule the RTC alarm for the given timestamp.
*
* :param uint32_t timestamp: When to schedule the IRQ
* :return: `0` on success or a negative value if an error occured. Possible
* :return: ``0`` on success or a negative value if an error occured. Possible
* errors:
*
* - ``-EINVAL``: RTC is in a bad state
......@@ -2148,7 +2154,7 @@ API_ISR(EPIC_INT_RTC_ALARM, epic_isr_rtc_alarm);
*
* :param uint8_t * dest: Destination buffer
* :param size: Number of bytes to read.
* :return: `0` on success or a negative value if an error occured. Possible
* :return: ``0`` on success or a negative value if an error occured. Possible
* errors:
*
* - ``-EFAULT``: Invalid destination address.
......@@ -2162,7 +2168,7 @@ API(API_TRNG_READ, int epic_trng_read(uint8_t *dest, size_t size));
*
* :param uint8_t * dest: Destination buffer
* :param size: Number of bytes to read.
* :return: `0` on success or a negative value if an error occured. Possible
* :return: ``0`` on success or a negative value if an error occured. Possible
* errors:
*
* - ``-EFAULT``: Invalid destination address.
......@@ -2290,7 +2296,7 @@ API(API_WS2812_WRITE, void epic_ws2812_write(uint8_t pin, uint8_t *pixels, uint3
*
* :param char* key: Name of the option to read
* :param int* value: Place to read the value into
* :return: `0` on success or a negative value if an error occured. Possible
* :return: ``0`` on success or a negative value if an error occured. Possible
* errors:
*
* - ``-ENOENT``: Value can not be read
......@@ -2304,7 +2310,7 @@ API(API_CONFIG_GET_INTEGER, int epic_config_get_integer(const char *key, int *va
*
* :param char* key: Name of the option to read
* :param bool* value: Place to read the value into
* :return: `0` on success or a negative value if an error occured. Possible
* :return: ``0`` on success or a negative value if an error occured. Possible
* errors:
*
* - ``-ENOENT``: Value can not be read
......@@ -2317,13 +2323,13 @@ API(API_CONFIG_GET_BOOLEAN, int epic_config_get_boolean(const char *key, bool *v
* Read a string from the configuration file.
*
* If the buffer supplied is too small for the config option,
* no error is reported and the first `buf_len - 1` characters
* no error is reported and the first ``buf_len - 1`` characters
* are returned (0 terminated).
*
* :param char* key: Name of the option to read
* :param char* buf: Place to read the string into
* :param size_t buf_len: Size of the provided buffer
* :return: `0` on success or a negative value if an error occured. Possible
* :return: ``0`` on success or a negative value if an error occured. Possible
* errors:
*
* - ``-ENOENT``: Value can not be read
......@@ -2338,7 +2344,7 @@ API(API_CONFIG_GET_STRING, int epic_config_get_string(const char *key, char *buf
*
* :param char* key: Name of the option to write
* :param char* value: The value to write
* :return: `0` on success or a negative value if an error occured. Possivle
* :return: ``0`` on success or a negative value if an error occured. Possivle
* errors:
*
* - ``-EINVAL``: Parameters out of range
......@@ -2556,7 +2562,7 @@ API(API_BLE_GET_COMPARE_VALUE, uint32_t epic_ble_get_compare_value(void));
/**
* Retrieve the (file) name of the last pairing which was successful.
*
* :return: `0` on success or a negative value if an error occured. Possible
* :return: ``0`` on success or a negative value if an error occured. Possible
* errors:
*
* - ``-ENOENT``: There was no successful pairing yet.
......@@ -2571,7 +2577,7 @@ API(API_BLE_GET_LAST_PAIRING_NAME, int epic_ble_get_last_pairing_name(char *buf,
* The name might be empty if the peer device does not expose it or
* if it has not yet been read from it.
*
* :return: `0` on success or a negative value if an error occured. Possible
* :return: ``0`` on success or a negative value if an error occured. Possible
* errors:
*
* - ``-ENOENT``: There is no active connection at the moment.
......@@ -2588,7 +2594,7 @@ API(API_BLE_GET_PEER_DEVICE_NAME, int epic_ble_get_peer_device_name(char *buf, s
* proceed and complete the pairing process. If called with ``false``, the
* pairing procedure will be aborted.
*
* :param bool confirmed: `true` if the user confirmed the compare value.
* :param bool confirmed: ``true`` if the user confirmed the compare value.
*
* .. versionadded:: 1.16
*/
......@@ -2615,8 +2621,8 @@ API(API_BLE_COMPARE_RESPONSE, void epic_ble_compare_response(bool confirmed));
* When switching applications new bondings are automatically
* disallowed and scanning is stopped.
*
* :param bool bondable: `true` if new bondings should be allowed.
* :param bool scanner: `true` if scanning should be turned on.
* :param bool bondable: ``true`` if new bondings should be allowed.
* :param bool scanner: ``true`` if scanning should be turned on.
*
* .. versionadded:: 1.16
*/
......@@ -2625,9 +2631,9 @@ API(API_BLE_SET_MODE, void epic_ble_set_mode(bool bondable, bool scanner));
/**
* Retrieve a scan report from the queue of scan reports.
*
* :param struct epic_scan_report* rpt: Pointer where the report will be stored.
* :param struct\ epic_scan_report* rpt: Pointer where the report will be stored.
*
* :return: `0` on success or a negative value if an error occured. Possible
* :return: ``0`` on success or a negative value if an error occured. Possible
* errors:
*
* - ``-ENOENT``: No scan report available
......@@ -2639,11 +2645,11 @@ API(API_BLE_GET_SCAN_REPORT, int epic_ble_get_scan_report(struct epic_scan_repor
* Send an input report to the host.
*
* :param uint8_t report_id: The id of the report to use. 1: keyboard, 2: mouse, 3: consumer control
* :param uint8_t *data: Data to be reported.
* :param uint8_t* data: Data to be reported.
* :param uint8_t len: Length in bytes of the data to be reported. Maximum length is 8 bytes.
*
* :return: `0` on success, `1` if the report is queued or a negative value if an error occured. Possible
* errors:
* :return: ``0`` on success, ``1`` if the report is queued or a negative value
* if an error occured. Possible errors:
*
* - ``-EIO``: There is no host device connected or BLE HID is not enabled.
* - ``-EAGAIN``: There is no space in the queue available. Try again later.
......
......@@ -11,6 +11,7 @@
#include "queue.h"
#else
typedef unsigned int size_t;
typedef int bool;
typedef void *QueueHandle_t;
#endif /* __SPHINX_DOC */
......
......@@ -48,6 +48,7 @@ formatter_blacklist=(
lib/vendor/
openocd/
docker/
Documentation/hawkmoth/
)
for source_file in "$@"; do
......
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