Documentation Generation

These instructions will walk you through generating the MCUXpresso SDK’s documentation on your local system using the same documentation sources as we use to create the online documentation found at https://mcuxpresso.nxp.com/mcuxsdk/latest/html/index.html

Documentation overview

As inspired by Zephyr Project, MCUXPresso SDK content is written using the reStructuredText markup language (.rst file extension), markdown with Sphinx extensions, and processed using Sphinx to create a formatted stand-alone website. Developers can view this content either in its raw form as .rst markup, .md files, or you can generate the HTML content and view it with a web browser directly on your workstation. This same .rst/.md content is also fed into the Zephyr Project’s public website documentation area (with a different theme applied).

You can read details about reStructuredText, and Sphinx from their respective websites.

The project’s documentation contains the following items:

• ReStructuredText/Markdown source files used to generate documentation found at the https://mcuxpresso.nxp.com/mcuxsdk/ website. Most of the reStructuredText/Markdown sources are found in the /docs directory, but others are stored within the code source tree near their specific component (such as /examples)

• Doxygen-generated material used to create all API-specific documents also found at https://mcuxpresso.nxp.com/mcuxsdk/

Schematic of the documentation build process

The reStructuredText/Markdown files are processed by the Sphinx documentation system, and make use of the breathe extension for including the doxygen-generated API material. Additional tools are required to generate the documentation locally, as described in the following sections.

Installing the documentation processors

Please refer to the installation guide at Installation

Documentation presentation theme

Sphinx supports easy customization of the generated documentation appearance through the use of themes. Replace the theme files and do another west doc html and the output layout and style is changed. The read-the-docs theme is installed as part of the install_py_requirements step you took in the getting started guide.

Running the documentation processors

The /docs directory in your cloned copy of the MCUXpresso SDK project git repo has all the .rst/.md source files, extra tools, and Makefile for generating a local copy of the MCUXpresso SDK project’s technical documentation. Assuming the local MCUXpresso SDK project copy is in a folder mcuxpresso-sdk in your home folder, here are the commands to generate the html content locally:

cd ~/mcuxpresso-sdk/mcuxsdk/docs

west doc html

west doc pdf

Warning

The documentation build system creates copies in the build directory of every .rst/.md file used to generate the documentation, along with dependencies referenced by those .rst/.md files.

This means that Sphinx warnings and errors refer to the copies, and not the version-controlled original files in MCUXpresso SDK. Be careful to make sure you don’t accidentally edit the copy of the file in an error message, as these changes will not be saved.

Depending on your development system, it will take up to 15 minutes to collect and generate the HTML content. When done, you can view the HTML output with your browser started at docs/_build/html/index.html and if generated, the PDF file is available at docs/_build/latex/mcuxsdk.pdf.

If you want to build the documentation from scratch just delete the contents of the build folder and run west doc html again.

Note

If you add or remove a file from the documentation, you need to re-run CMake.

On Unix platforms a convenience Makefile under the docs/ folder can be used to build the documentation directly from there:

cd ~/mcuxpresso-sdk/mcuxsdk/docs

# To generate HTML output
make html

# To generate PDF output
make pdf

Developer-mode Document Building

When making and testing major changes to the documentation, we provide an option to only build the HTML output with specified modules so the doc build process run faster.

To enable this mode, set the following option when invoking west doc:

-t module_name_a,module_name_regex_a

e,g. -t gsd,dev_.* will only build the HTML with gsd module and other modules
starts with dev_

Custimizing Example Readme Scope

MCUXpresso SDK provides plenty of example projects, building all example readme document needs long time. We provide an option to only build some specific examples, then developer can test the required example readme quickly.

Use --example_scope= when invoking west doc to specify the example scope:

cd ~/mcuxpresso-sdk/mcuxsdk/docs

# To generate example readme for all the examples in folder examples/demo_apps
west doc html -t examples --example_scope=examples/demo_apps

Note

When using --example_scope=, the example readme won’t be shown in the html mainpage. You need to go to folder _build/html/examples to see the result. For example, if --example_scope=examples/demo_apps, then open _build/html/examples/demo_apps/index.html to see the result.

Viewing generated documentation locally

The generated HTML documentation can be hosted locally with python for viewing with a web browser:

$ python3 -m http.server -d _build/html --bind 127.0.0.1

# Or you can invoke by west extension
$ west doc view