The vcs_link should only run for the HTML builder, since it is the only
target of this extension. The other builders do not have the templates
instance, making them fail.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Add vcs_link extension. The extension can be used to obtain VCS (Git)
URLs for given Sphinx documents.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The setup() method is trying to find the zephyr repository by name,
but it's not passing allow_paths=False to the west method it uses to
search.
That may lead to unpredictable results depending on what the current
working directory is in the calling environment.
For robustness, disallow paths and make sure we are only searching for
the zephyr project by name.
Add some more comments to explain what is going on and clean up the
empty string handling while we're here.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
The extension was not evaluating the GENERATE_HTML option correctly. The
get_doxygen_option returns a `List[str]`, not a `str`.
This effectively means that the Zephyr apidoc has not been updated for a
while as the extension was not moving the output to the final
destination folder.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
QUIET flag is now overriden according to the `doxyrunner_silent`
configuration value.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This change will process Doxygen output and will map it to the Sphinx
logger. Things like errors and warnings will be mapped to actual Sphinx
logger error and warnings. In practice this means that when Doxygen
throws a warning and Sphinx is run in "-W" (warning as error) mode, the
build will fail. It also has some other advantages such as the
possibility of filtering issues using the warnings_filter extension.
It is also expected that CI errors not being displayed issue is fixed
with this change.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The eager_only is currently breaking the usage of the `.. only``
directive, so remove it. Documentation seems to build fine without it,
so it has been removed for now.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Add a new extension to support the :kconfig: role and .. kconfig::
directive. This removes the need of using :option:.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Sphinx provides a way to persist data across builds: the
BuildEnvironment. The build environment is automatically managed by
Sphinx, so there is no need to take care of loading/dumping cache files.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Use file hashes instead of paths and modification times. This method is
fits better on systems using cache mechanisms. Note that hash is
computed using content obtained in UTF-8 text mode for portability
reasons.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Path.rename() uses os.rename() internally. Per the Python docs:
The operation may fail on some Unix flavors if src and dst are on
different filesystems.
Since 'src_adjusted' is in a temporary directory, on my flavor of
Unix, that's in /tmp, which is indeed on a different filesystem than
'dst', a destination in the doc build directory on my root filesystem.
This is causing the following error when I build the docs:
Handler <function sync_contents at 0x7f9b8fca9c10> for event
'builder-inited' threw an exception (exception: [Errno 18] Invalid
cross-device link: '/tmp/tmpfscfo20o/index.rst' ->
'/home/mbolivar/zp/zephyr/doc/_build/src/reference/drivers/index.rst')
Fix this by using shutil.move() instead of Path.rename(). The shutil
function handles cross-filesystem moves correctly. It did not take a
path-like object for both its src and dst arguments until Python 3.9,
though, so we need to convert to strings for portability on earlier
but still supported versions.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
When including other rst files (via .. include::) the existence of the
included file may depend on when the _adjust routine is called, so only
ignore absolute paths.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
PosixPath or WindowsPaths are not portable, so using them on pickle
files, which can potentially be re-used is not safe. Changed to use the
posix path as a string.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This needs to use 'main' for its default now.
Without this patch, GitHub redirects to main, but displays a banner
that says 'Branch not found, redirected to default branch' at the top.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Make HTML output optional. The extension checks the `GENERATE_HTML`
option to check if active.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
zephyr.doxyrunner Sphinx extension is meant to replace multiple Python
and CMake scripts into a single Sphinx extension.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Explicitely mention that these files are intentionally empty. These
changes should make compliance checks pass.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
