Docs Generation: `breathe/sphinx` Warning: doxygenfile: Cannot find file "lv_button.h #6924

vwheeler63 · 2024-09-24T09:24:30Z

LVGL version

V9.3

What happened?

In the docs generation I'm currently getting a large number of warnings that look like this:

<tmpdir>\API/widgets/button/lv_button.rst:8: WARNING: doxygenfile: Cannot find file "lv_button.h

and simultaneously, the API text is not showing up in the generated documentation. I'm not sure if it is something about my local system since the https://docs.lvgl.io/master/API/widgets/button/lv_button.html page is obviously showing the Doxygen-extracted documentation, but on my local system, I am getting this instead:

I haven't changed anything in the doc-generating .py files, so I need guidance. Hopefully Kevin ( @kdschlosser ) knows more.

I also note that there is a missing closing quotation mark in the error message and wonder if this might be relevant.

In PR #6916, Kevin stated:

the problem with the not finding files is the reason why I went looking for a breathe replacement. Breathe is designed to read one header file at a time. The problem with that is the use of a configuration header file that exposes the various portions of the API. In order to allow everything to work properly each and every single header file in LVGL would need to include the config header file. How LVGL works currently is it includes the config header file a single time when lvgl.h is included and the config settings propagate because the compiler sees the macros from the config file because that file was loaded. But if using the compiler to read a single header file that information is now unavailable. It is a limitation of breathe and it is something that is not going to be fixed upstream in breathe unless the guy gets paid to fix it.

The other issue with breathe is it doesn't use full paths when generating documentation using the .. doxygenfile:: directive which is what the doc build system is using. So if you have header files that have the same name you run into problems.

My concern is: will the API content generate correctly in the actual build system when it is not doing so on my local system? There was a point a few months ago when the whole thing (under https://github.com/kdschlosser/lvgl documentation-fixes branch) was generating entirely without errors on my system if I am remembering correctly. Yet, the existing documentation is getting its API info. Is it safe to proceed or does this need to be repaired?

This is the last type of Sphinx warning remaining. There are 332 of them.

Kind regards,
Vic

How to reproduce?

cd ./docs/
python build.py clean develop skip_latex

The text was updated successfully, but these errors were encountered:

kisvegabor · 2024-09-25T11:22:36Z

Is it resolved by #6928?

vwheeler63 · 2024-09-25T11:35:04Z

Is it resolved by #6928?

No, not this particular warning. At my end, all sphinx warnings are handled but this one.

kisvegabor · 2024-09-26T08:09:13Z

I see, let's what happens with the GitHub docs build when your changes are merged. We will see if there are any error in the CI's logs. See e.g. here

vwheeler63 · 2024-09-26T10:23:04Z

@kdschlosser Hi, Kevin! Are these normal warnings (see link from above)?

@kisvegabor Hi, Gábor, is https://docs.lvgl.io/master/API/ currently reflecting the result of that build/deploy?

kdschlosser · 2024-09-26T14:13:34Z

That is everything that has not been documented.....

Git-r-done!!!

LOL

vwheeler63 · 2024-09-26T16:57:06Z

@kdschlosser So, are these normal warnings? They aren't supposed to generate the API documentation locally? I thought sure that when I was initially working from your kdschlosser/lvgl repository that when I did the docs generation that it did generate the API docs locally on my workstation.

Am I right (that it was generating the API docs locally)? In which case I have to assume it something I caused here locally?

Or am I wrong and I can I safely ignore them for now?

kdschlosser · 2024-09-27T02:14:35Z

Remember I had added it writing that output to a file instead of outputting it to screen. That was apart of that PR i killed due to there being way to many merge conflicts. Once all of the changes to the doxygen stuff was done I was going to create another PR to handle all of the ReST issues and another PR to add that check to fail the build if something has not been documented.

vwheeler63 · 2024-09-27T07:16:14Z

@kisvegabor is the current on-line docs a result of the build you did above? Or is the test-build results in an alternative location?

kisvegabor · 2024-09-30T12:51:49Z

is https://docs.lvgl.io/master/API/ currently reflecting the result of that build/deploy?

Yes, it's generated during the docs-build.

vwheeler63 · 2024-09-30T13:09:19Z

is https://docs.lvgl.io/master/API/ currently reflecting the result of that build/deploy?

Yes, it's generated during the docs-build.

So the fact that I am seeing API docstrings (e.g. https://docs.lvgl.io/master/API/lv_init.html) in the API pages means it is still working (being generated on Ubuntu), and only not working on my PC. Am I interpreting that correctly?

vwheeler63 · 2024-10-01T17:46:06Z

cc: @kdschlosser @kisvegabor

SOLVED!!!

The problem that triggered the above was that the code in build.py was not written to anticipate a TMPDIR environment variable having a different drive than the LVGL project. This is something different (quirky?) about Windows that if you issue the command:

E:\Dev\Lib\Emb\lvgl\vwheeler63\lvgl\docs>  cd R:\TMPDIR\some_directory
E:\Dev\Lib\Emb\lvgl\vwheeler63\lvgl\docs>  |

it only changes the default directory on R:, but does not change the CURRENT DEFAULT directory (which is reflected in the command prompt). There is one more command required to change CURRENT DEFAULT directory:

E:\Dev\Lib\Emb\lvgl\vwheeler63\lvgl\docs>  R:
R:\TMPDIR\some_directory>  |

Note the new CURRENT DEFAULT directory is now reflected in the command prompt.

build.py was issuing this command (I'm simplifying a bit):

cmd(f'cd "{temp_directory}" && doxygen Doxyfile')

where temp_directory was R:\TMPDIR\some_directory, but the CURRENT DEFAULT directory was E:\Dev\Lib\Emb\lvgl\vwheeler63\lvgl\docs. This got sent to the Python os.system(cmd_string) function, which effectively was trying to execute:

cd "R:\TMPDIR\some_directory"   &&   doxygen Doxyfile

So the intended result of changing the CURRENT DEFAULT directory did not succeed (same as in the command prompts above). This caused Doxygen to be running on the wrong drive. Since the OUTPUT_DIRECTORY is configured as ".", the generated files were going to the wrong place.

It either needed an additional command to change drives (R:) -- which would have had to have been

cd "R:\TMPDIR\some_directory"   &&   R:   &&   doxygen Doxyfile

Or it needed this, which accomplishes the desired end result in a simpler way.

    os.chdir(temp_directory)
    cmd('doxygen Doxyfile')
    os.chdir(base_path)

Note that os.chdir() DOES change drives, and thus changes the CURRENT DEFAULT directory. (A quirky thing about Windows that the port of Python to Windows had to deal with, and os.chdir() handles it internally.)

I had to deal with 2 more work-arounds to prevent spinx-build from aborting, and now I have the desired result:

generated locally on Windows instead of the "Cannot find file" error from above.

Gábor, would you like me to submit these fixes in a PR? Or submit it with the task I am working on?

Kind regards,
Vic

kisvegabor · 2024-10-02T10:19:34Z

Great!

    os.chdir(temp_directory)
    cmd('doxygen Doxyfile')
    os.chdir(base_path)

This approach looks way better to me. So yes, please send a PR 🙂

@kdschlosser

...in the case where TMPDIR environment variable pointed to a drive different than the LVGL project directory. (TMPDIR is used by Python `tempfile.mkdtemp()` used in `build.py`.) The result was on Windows Doxygen was running in the LVGL project's `./docs/` directory instead of the temporary directory where it was intended to run, causing Doxygen to generate XML files for the API pages in in the wrong place. The solution was to replace the attempted `cd` with a cross-platform compatible `cd` built into Python's `os` library by temporarily having the `build.py` script change directories to where Doxygen should run and change back again after running it. Additionally: 1. Handled 2 Python warnings where a regex string was using an illegal escape sequence by making it a "raw" string, since the escape backslash needs to be passed un-interpreted to the regex. 2. Replaced `build.py`s get_version() function with one that works on both Linux and Windows platforms. Credit: @kdschlosser. Resolves lvgl#6924.

vwheeler63 · 2024-10-02T16:41:22Z

This approach looks way better to me. So yes, please send a PR 🙂

Done! PR #6990

vwheeler63 mentioned this issue Sep 24, 2024

fix(docs): fix most sphinx warnings #6916

Merged

vwheeler63 linked a pull request Oct 2, 2024 that will close this issue

fix: docs error blocking API-doc generation under Windows... #6990

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs Generation: `breathe/sphinx` Warning: doxygenfile: Cannot find file "lv_button.h #6924

Docs Generation: `breathe/sphinx` Warning: doxygenfile: Cannot find file "lv_button.h #6924

Docs Generation: breathe/sphinx Warning: doxygenfile: Cannot find file "lv_button.h #6924

Docs Generation: breathe/sphinx Warning: doxygenfile: Cannot find file "lv_button.h #6924

Comments

LVGL version

What happened?

How to reproduce?

Docs Generation: `breathe/sphinx` Warning: doxygenfile: Cannot find file "lv_button.h #6924

Docs Generation: `breathe/sphinx` Warning: doxygenfile: Cannot find file "lv_button.h #6924