The Sphinx ``.. only::`` directive is limited to handling only
conditional text and can't handling conditional use of directives
For example,
```
.. only:: test
.. automodule:: west.runners.core
:members:
```
is not handled. This PR monkey patches the handling of the existing
``.. only::`` directive done by Sphinx.
See https://github.com/pfalcon/sphinx_selective_exclude for details.
Licensing amended to Apache 2.0 with permission from the author.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The directive is not generating the right "mkdir" steps when used with
the :app: option. Fix it.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
I've collected some of the common issues encountered with doc reviews
into a new contributing document, and included use of the
Zephyr-specific extension for generating code building examples.
Updated conf.py and created an external list of substitutions making it
easier to manage them without editing the sphinx conf file (and
documented this).
Tweaked the comments in the application.py extension python code to
render better in the generated doc that extracts these comments (keeps
the documentation in the python code too to ease maintenance when
updates are made).
Updated the sample template to mention use of this sphinx extension.
fixes: #6831fixes: #6811
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
When sphinx-build is run under Python 2, running e.g. 'make html' in
doc/ currently causes the following error:
Exception occurred:
File "conf.py", line 128, in <module>
from lexer.DtsLexer import DtsLexer
ImportError: No module named lexer.DtsLexer
The problem is that doc/extensions/lexer/ contains no __init__.py file,
which prevents Python 2 from finding submodules in it[1].
The problem does not occur for Python 3, due to implicit namespaces
packages:
https://www.python.org/dev/peps/pep-0420/
Add an empty __init__.py to doc/extensions/lexer/ to fix building when
sphinx-build uses Python 2 (2.7 is still the version recommended on the
Sphinx homepage). This won't alter the behavior for Python 3.
(doc/extensions is added to the search path at the beginning of conf.py
and so doesn't need an __init__.py. doc/extensions/zephyr already has an
empty __init__.py.)
[1] https://docs.python.org/2/tutorial/modules.html#packagesFixes#6851
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
In order to properly support documenting building on both UNIX and
Windows, a new "host-os" option has been added to the Python script,
alongside with a switch to ninja as the default generator.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Rather than continuing to add build system goals, let's just trust the
user to do the right thing. The only special case is build, which is
the default goal.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
Since run is also used commonly, add it as a goal as well for those
users of the extension that want to create a sequence similar to:
$ make
$ make run
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
The new :compact: option allows for a single block of code output
without additional newlines or comments.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
New arguments added:
- conf: -DCONF_FILE=<>
- gen-args: Additional arguments to pass to CMake
- build-args: Additional arguments to pass to Make or Ninja
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
CMake requires "-D" for every macro that is passed into it. Add the
relevant "-D" for the Make variant of the extension.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
David B. Kinder