search

breathe-doc / breathe

ReStructuredText and Sphinx bridge to Doxygen
https://breathe-doc.org
Other
752 stars 200 forks source link

Cannot build documentation from GitHub source tarballs (git repo assumed) #583

Open kloczek opened 4 years ago

kloczek commented 4 years ago

In case od https://files.pythonhosted.org/packages/source/b/breathe/breathe-4.21.0.tar.gz there is no documentation/ and examples/ directories. In case if tagged tar ball https://github.com/michaeljones/breathe//archive/v4.21.0/python-breathe-4.21.0.tar.gz looks like some files are missig and sphinx cannot generate documentation

+ sphinx-build -b man -d python-breathe documentation/source .
Running Sphinx v3.2.1
fatal: not a git repository (or any parent up to mount point /home/tkloczko)
Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).
/usr/lib/python3.8/site-packages/breathe/directives.py:836: RemovedInSphinx40Warning: The app.add_stylesheet() is deprecated. Please use app.add_css_file() instead.
  app.add_stylesheet(breathe_css)
WARNING: html_static_path entry '_static' is placed inside outdir
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 36 added, 0 changed, 0 removed
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/class.rst:57: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/nutshell/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/class.rst:76: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/template_specialisation/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/class.rst:89: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/template_specialisation/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/class.rst:111: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/nutshell/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/class.rst:132: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/nutshell/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/class.rst:153: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/group/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/class.rst:174: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/nutshell/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/class.rst:198: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/class/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/class.rst:227: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/nutshell/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/class.rst:250: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/qtsignalsandslots/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/define.rst:17: WARNING: doxygendefine: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/c_file/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/domains.rst:27: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/class/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/domains.rst:53: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/class/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/domains.rst:78: WARNING: doxygenfunction: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/class/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/domains.rst:81: WARNING: doxygenfunction: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/alias/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/domains.rst:124: WARNING: doxygentypedef: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/typedef/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/domains.rst:127: WARNING: doxygentypedef: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/typedef/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/domains.rst:130: WARNING: doxygenclass: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/typedef/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/domains.rst:163: WARNING: doxygenenumvalue: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/enum/xml/index.xml
/home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/documentation/source/domains.rst:166: WARNING: doxygenenumvalue: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/specific/enum/xml/index.xml

Exception occurred:
  File "/usr/lib/python3.8/site-packages/breathe/directives.py", line 697, in get_mtime
    raise MTimerError('Cannot find file: %s' % os.path.realpath(filename))
breathe.directives.MTimerError: Cannot find file: /home/tkloczko/rpmbuild/BUILD/breathe-4.21.0/examples/doxygen/class/xml/index.xml
The full traceback has been saved in /tmp/sphinx-err-zbfsa9hs.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
vermeeren commented 4 years ago

@kloczek I checked version 4.20.0, 4.8.0 from 2018 and 4.0.0 from 2015 and they are all the same, so this appears intentional.

For every release I run this (which complains a bit about using twine instead), the second command has been in the readme for 4 years or so now.

git clean -xdf
python setup.py sdist bdist_wheel upload

I suppose something of the packaging tooling automatically cleans up the source tree during packaging to only retain the actual Python source code. Whether this is convention for Python or PyPI I do not know, that would be something to have a look at.

vermeeren commented 4 years ago

@kloczek As for GitHub tarball, from your logs:

fatal: not a git repository (or any parent up to mount point /home/tkloczko)

Some of the scripts used to generate documentation probably assume we are always building from the git repo, it likely uses this to fetch version (tag/commit sha) information.

kloczek commented 4 years ago

Some of the scripts used to generate documentation probably assume we are always building from the git repo, it likely uses this to fetch version (tag/commit sha) information.

That message was generated by sphinx-build -b man -d python-breathe documentation/source . command. Autogenerated by gitlab/githug tar ball dowloaded from git tag does not contain git metadata.

vermeeren commented 4 years ago

@kloczek To clarify, the documentation building problem from source tarballs is indeed a bug, will label and update title to reflect this. Patches are welcome as usual.

Edit: as for the contents of the PyPI source package, I consider this intentional at this point unless I get some specific info on this.