Page MenuHomePhabricator

cmake: TF-M documentation build issue
Open, LowPublic

Description

There is an issue when building the TF-M documentation using the command line CMake commands provided by the Build instructions TF-M guide:

$ cmake -S . -B cmake_doc -DTFM_PLATFORM=mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake
$ **cmake --build cmake_doc -- tfm_docs_userguide_html tfm_docs_userguide_pdf**

Output:
make: *** No rule to make target 'tfm_docs_userguide_html'. Stop.

There is the same error for the reference manual.
It is needed to generate the whole documentation manually.

Event Timeline

MartinaHanusovaNXP triaged this task as Low priority.Wed, Apr 28, 10:30 AM
MartinaHanusovaNXP created this task.

Hi Martina.

Could you please confirm the ref tag which you are trying to build the documentation against ?

I have tested that in latest HEAD -> cd22d1bd7f96ece9f88df87445f7be138de380b3 the HTML target of the documentation works. The pdf generation is currently not working, but that is a Latex issue, which is being triaged. The targets should be present though.

I used the following command to build and test only the html target.

cmake -S . -B cmake_doc -DTFM_PLATFORM=mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake
cmake --build cmake_doc -- tfm_docs_userguide_html

If the tfm_docs_userguide_html target is not present, I could verify that the dependencies are present in the build enviroment and detected by CMake

-- Found PythonInterp: /usr/bin/python3 (found suitable version "3.7.10", minimum required is "3") 
-- Found Sphinx: /usr/local/bin/sphinx-build (found version "2.0.1") 
CMake Warning (dev) at /opt/cmake-3.18.0-Linux-x86_64/share/cmake-3.18/Modules/FindPackageHandleStandardArgs.cmake:273 (message):
  The package name passed to `find_package_handle_standard_args` (PY_M2R)
  does not match the name of the calling package (PythonModules).  This can
  lead to problems in calling code that expects `find_package` result
  variables (e.g., `_FOUND`) to follow a certain pattern.
Call Stack (most recent call first):
  cmake/FindPythonModules.cmake:60 (find_package_handle_standard_args)
  docs/CMakeLists.txt:14 (find_package)
This warning is for project developers.  Use -Wno-dev to suppress it.

-- Found PY_M2R: /usr/local/lib/python3.7/dist-packages/m2r.py  
CMake Warning (dev) at /opt/cmake-3.18.0-Linux-x86_64/share/cmake-3.18/Modules/FindPackageHandleStandardArgs.cmake:273 (message):
  The package name passed to `find_package_handle_standard_args`
  (PY_SPHINX-RTD-THEME) does not match the name of the calling package
  (PythonModules).  This can lead to problems in calling code that expects
  `find_package` result variables (e.g., `_FOUND`) to follow a certain
  pattern.
Call Stack (most recent call first):
  cmake/FindPythonModules.cmake:60 (find_package_handle_standard_args)
  docs/CMakeLists.txt:14 (find_package)
This warning is for project developers.  Use -Wno-dev to suppress it.

-- Found PY_SPHINX-RTD-THEME: /usr/local/lib/python3.7/dist-packages/sphinx_rtd_theme/__init__.py  
CMake Warning (dev) at /opt/cmake-3.18.0-Linux-x86_64/share/cmake-3.18/Modules/FindPackageHandleStandardArgs.cmake:273 (message):
  The package name passed to `find_package_handle_standard_args`
  (PY_SPHINXCONTRIB.PLANTUML) does not match the name of the calling package
  (PythonModules).  This can lead to problems in calling code that expects
  `find_package` result variables (e.g., `_FOUND`) to follow a certain
  pattern.
Call Stack (most recent call first):
  cmake/FindPythonModules.cmake:60 (find_package_handle_standard_args)
  docs/CMakeLists.txt:14 (find_package)
This warning is for project developers.  Use -Wno-dev to suppress it.

-- Found PY_SPHINXCONTRIB.PLANTUML: /usr/local/lib/python3.7/dist-packages/sphinxcontrib/plantuml.py  
-- Found Java: /usr/bin/java (found suitable version "1.8.0.282", minimum required is "1.8") found components: Runtime 
CMake Warning (dev) at /opt/cmake-3.18.0-Linux-x86_64/share/cmake-3.18/Modules/FindPackageHandleStandardArgs.cmake:273 (message):
  The package name passed to `find_package_handle_standard_args` (Plantuml)
  does not match the name of the calling package (PlantUML).  This can lead
  to problems in calling code that expects `find_package` result variables
  (e.g., `_FOUND`) to follow a certain pattern.
Call Stack (most recent call first):
  cmake/FindPlantUML.cmake:63 (find_package_handle_standard_args)
  docs/CMakeLists.txt:15 (find_package)
This warning is for project developers.  Use -Wno-dev to suppress it.

-- Found Plantuml: /usr/share/plantuml/plantuml.jar (found version "8024") 
-- Found Doxygen: /usr/bin/doxygen (found suitable version "1.8.11", minimum required is "1.8.0") found components: doxygen dot 
-- Found LATEX: /usr/bin/latex  found components: PDFLATEX 
-- ---------- Display crypto configuration - start --------------
......
......
......
-- Configuring done
-- Generating done
-- Build files have been written to: .....

The requirements for building the documentation are listed here

Hi Minos,

thank you for your help, now after upgrading/downgrading all modules according to the requirements it works.

Before I had a compilation error in the newest version of Sphinx (version 3.5.4):

Scanning dependencies of target tfm_docs_sphinx_cfg
[  0%] Generating temp/conf.py
[  0%] Built target tfm_docs_sphinx_cfg
Scanning dependencies of target tfm_docs_userguide_html
[100%] Generating user_guide/html/index.html, user_guide/html
Running Sphinx v3.5.4

Exception occurred:
  File "/usr/local/lib/python3.7/dist-packages/sphinx/registry.py", line 267, in add_source_parser
    for filetype in parser.supported:
AttributeError: 'str' object has no attribute 'supported'
The full traceback has been saved in /tmp/sphinx-err-t_7r15qg.log, if you want to report the issue to the developers.

But it was solved by downgrading to version 1.8.4.

Sorry for the complications,
Martina

AndreyButokNXP added a comment.EditedThu, Apr 29, 5:47 AM

Hi Minos,
Is this a compatibility issue and the TFM doc build system can be upgraded, or this a bug in the latest version of Sphinx?

As all users will use the latest version of Sphinx, could you upgrade to it and reproduce the issue?

Thanks,
Andrej

At a quick glance this seems to be an m2r bug: https://github.com/sphinx-doc/sphinx/issues/8705. m2r seems to be abandoned, switching to m2r2 might be a workaround, as that seems to have a fix merged.
For now the best might be to stick to the documented package versions. I am wondering if the requirements file should be more strict on Spninx version.