We have directives in conf.py to create redirect links for docs that
have been moved around because of content reorganization. Reduce the
number of messages written out while debugging was going on and add some
comments to conf.py to explain how the directive works.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
In order to expose west to the majority of users, default to 'all'
instead of 'cmake' in the 'tool' option. This means that, unless
otherwise specified, build instructions will be generated for both west
and cmake by default.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
In order to simplify the current implementation and to prepare for a
change where we default to west as the standard build tool, partially
refactor the generation of cmake-based build instructions:
- Introduce `cd-into` as boolean flag that controls whether build
instructions are generated from the current working directory or from
inside the actual app folder. In the case of cmake, this includes
changing into the build folder to run ninja or make.
- Default to building from the current working directory, in the case of
cmake using the `-B` flag to create the build folder.
- Remove the usage of ZEPHYR_BASE with the `zephyr-app` option.
The option itslef is kept fsince it has semantic value, and a comment is
added when used.
- Consolidate the _generate_make and _generate_ninja functions into a
common code block inside _generate_cmake.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Several of our extensions don't declare they are parallel read or
write safe. Upon inspection, they are.
Not declaring parallel read safety defeats a lot of the speed ups that
are possible when using SPHINXOPTS="-j=auto", so mark the extensions
safe and get the performance back.
Signed-off-by: Marti Bolivar <marti@foundries.io>
Fixes pylint warnings like this one:
doc/conf.py:325:0: W1401: Anomalous backslash in string: '\s'.
String constant might be missing an r prefix.
(anomalous-backslash-in-string)
The reason for this warning is that backslash escapes are interpreted in
non-raw (non-r-prefixed) strings. For example, '\a' and r'\a' are not
the same string (first one has a single ASCII bell character, second one
has two characters).
It just happens that there's no \s (or \., or \/) escape for example,
and '\s' turns into two characters (as needed for a regex). It's risky
to rely on stuff like that regexes though. Best to make them raw strings
unless they're super trivial.
Also note that '\s' and '\\s' turn into the same string.
Another tip: A literal ' can be put into a string with "blah'blah"
instead of 'blah\'blah'.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Discovered with pylint3.
Use the placeholder name '_' for unproblematic unused variables. It's
what I'm used to, and pylint knows not to flag it.
Python tip:
for i in range(n):
some_list.append(0)
can be replaced with
some_list += n*[0]
Similarly, 3*'\t' gives '\t\t\t'.
(Relevant here because pylint flagged the loop index as unused.)
To do integer division in Python 3, use // instead of /.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Not needed in Python. Detected by check C0325 in pylint3.
Also replace an
if len(tag):
with just
if tag:
Empty strings, byte strings, lists, etc., are falsy in Python.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
In order to simplify the usage of `west build`, take a positional
argument with the source directory instead of requiring the `-s,
--source-dir` flag. This makes it easier and quicker to invoke west when
building, as well as being consistent with CMake.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
When generating instructions for both west and CMake, use paragraphs and
literal blocks for better layout.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Overhaul the application extension in order to modularize its structure
and add support for building, flashing and debugging with west.
Both west and CMake are now supported, even at the same time, in which
case instructions for both will be generated.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Correct the handling of the HOST_OS list so that we do not insert an
extra line break because of the 'all' entry and we correctly insert the
required comment.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
When referencing files from the git tree create a link to the file for
easy browsing of header files and other files of interest.
Borrowed from esspresif/esp-idf project and modified for Zephyr.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
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>
Marc Herbert