Open kloczek opened 3 years ago
@kloczek Will this change also mean that source and/or built Breathe docs are included in the PyPI distribution among perhaps other things? I'm not very familiar with setuptools to be honest.
That patch simple is hint for setuptools<>sphinx integration pointing to the directory where is config.py files. https://www.sphinx-doc.org/en/master/usage/advanced/setuptools.html
Without that small fix python setup.py build_sphinx
fails because by default that integration is using docs/
directory. In other words to fix that that can patch needs to be applied or directory with sphins files needs to be renamed to docs/
.
Than when that integration settings would be working it would be possible to use it to build documentation and for example test possible fixes in sphinx documentaion :)
@kloczek I understand, thanks for the info. I did some experimentation with the option but it appears this is not suited for Breathe as it directly invokes the Sphinx documentation builder plainly. This means required setup, such as Doxygen XML generation, is not done and you will get something like:
Exception occurred:
File "/.../breathe/breathe/file_state_cache.py", line 27, in _getmtime
raise MTimeError('Cannot find file: %s' % os.path.realpath(filename))
breathe.file_state_cache.MTimeError: Cannot find file: /.../breathe/examples/doxygen/class/xml/index.xml
As for the warning messages, it is (currently) expected that Breathe's doc builds emit a lot of warnings, I don't see anything too different from the current output with Sphinx 3.x series, so I suspect things will be mostly fine as usual. (CICD does also test new Sphinx, so major breakage should be detected automatically.)
Currently I don't see anything concrete to do with this issue as it's lacking anything concrete that we can still do, thoughts?
Thanks
It is possible to integrete calling doxygen or any other tool into copy.py. Otherr thing is ther sphinx has at least few native API doc generators.
Updated list of warnings for latest 4.34.0
On building my packages I'm using sphinx-build
command with -n
switch which shows warmings about missing references. These are not critical issues.
Here is the output with warnings:
You can peak on fixes that kind of issues in other projects https://github.com/latchset/jwcrypto/pull/289 https://github.com/click-contrib/sphinx-click/commit/abc31069 https://github.com/latchset/jwcrypto/pull/289 https://github.com/RDFLib/rdflib-sqlalchemy/issues/95 https://github.com/sissaschool/elementpath/commit/bf869d9e https://github.com/jaraco/cssutils/issues/21 https://github.com/pywbem/pywbem/pull/2895
@kloczek Thanks again. A lot of the warnings for Breathe's own doc should be fixed by #816.
On building my packages I'm using sphinx-build command with -n switch which shows warmings about missing references. These are not critical issues.
@kloczek You should get in the habit of using -W
instead of -n
. This is how readthedocs builds are typically done. Unresolved references are something I started attacking in #816, but I had to give up since the numerous modifications required to resolve the extra 251 nit picky warnings are counterintuitive to the subject of the docs (trust me on this - they're mostly about undocumented C++ namespaces or data structures).
Like you said: "they are not critical." That's why I focused on resolving the 245 basic warnings instead, not the "nit picky mode" that you posted. Doing so earlier could've helped prevent some regressions in v4.32. Incidentally, about 50+ nit picky warnings were resolved when all the basic warnings were resolved.
Don't worry. I'm only messenger. I'm reporting only what I see and I'm not expecting miracles 😃
First of all looks like setuptools<>sphinx integration is not done. Below patch fixes that:
(feel free to commit that or let me know if you want this as PR) With that patch documentation/Makefile file is no longer needed.
Than .. looks like new sphinx shows some warnings.