Breathe not generating any output for documented file

[bocajnotnef]

Hello!

I'm using Breathe/Doxygen/Sphinx to document a c++ project I'm a contributor on. Currently we have it all configured to generate documentation for a chunk of the files in our tools module, and it works perfectly on most of the files, but on some of them Breathe generates nothing or nearly nothing for the whole file.

An example:

This is a snapshot of the HTML docs; as you can see, there's docs for graph_utils.h and for macros.h, but nothing for grid.h

Here's the top of grid.h:

  #include <vector>                                                               

  #include "assert.h"                                                             
  #include "BitVector.h"                                                          

  namespace emp {                                                                 
  namespace Grid {                                                                

    template <typename CELL_TYPE> class Cell;                                     
    template <typename EDGE_TYPE> class VEdge;                                    
    template <typename EDGE_TYPE> class HEdge;                                    
    template <typename POINT_TYPE> class Point;                                   

    class Layout {                                                                
    private:                                                                      
      int width;                                                                  
      int height;                                                                 
      std::vector< std::vector<int> > regions;                                    
    public:                                                                       
      Layout(int w, int h) : width(w), height(h) { ; }                            
      Layout(const Layout &) = default;                                           
      ~Layout() { ; }                                                             
      Layout & operator=(const Layout &) = default;                               

      int GetWidth() const { return width; }                                      
      int GetHeight() const { return height; }                                    
      int GetNumRegions() const { return (int) regions.size(); }                  
      const std::vector<int> & GetRegion(int id) { return regions[id]; }

I don't see anything obvious that would be causing this to break.

We are using doxygen 1.8.11, sphinx 1.4.1 and breathe from the master branch.

To reproduce:

# get empirical
git clone https://github.com/devosoft/Empirical.git
cd Empirical
# assuming you have flex, bison etc., install the dependencies for the project:
make install-dependencies
# source the environment
source third-party/env/bin/activate
# build the docs
make doc
# open doc/_build/html/index.html, navigate to the Tools documentation, 
# drop to where "tools/grid.h" is and observe lack of documentation

If you look in build/doxydoc/xml/classemp_1_1Grid.xml you can see that doxygen sees all the things and generates XML for the file.

Any help would be appreciated!

[vitaut]

Are you using doxygenfile and what is the exact RST code? build/doxydoc/xml/classemp_1_1Grid.xml looks like the XML for class Grid, not file, so I'd check if the file XML is generated properly.

[bocajnotnef]

I am using doxygenfile--`doc/library/tools.rst" contains the directive:

**tools/grid.h**                                                                

.. doxygenfile:: tools/grid.h                                                   
   :project: Empirical                                                          

which is how the rest of the (working) directives look.

As for the xml, the file build/doxydoc/xml/grid_8h.xml exists and grepping through it for the names of various classes and funcitons specified in grid.h returns the correct results, so it appears to be correct.

[vitaut]

I don't see anything wrong and generating docs just for grid.h seems to work. Haven't tried the full project though.

[bocajnotnef]

Any changes on this, or any other information you need that would be helpful?

[vitaut]

I didn't have time to look into it. Could you confirm that the issue doesn't happen when you generate the docs only for grid.h without other headers?

[vermeeren]

I tried to reproduce this with Sphinx (1.7.4) + Breathe (4.9.0) locally, but could not get the docs to build.

preparing documents... done
Target:  emput... [ 57%] library/data/data                                                                                                                                                                                         
ParentKey:  [(<ASTNestedNameElement emp>, None), (<ASTNestedNameElement DataModuleRequisiteAdd<>>, <ASTTemplateParams template<> >)]

Exception occurred:
  File "/usr/lib/python3.6/site-packages/sphinx/domains/cpp.py", line 6102, in _resolve_xref_inner
    assert parentSymbol  # should be there
AssertionError
The full traceback has been saved in /tmp/sphinx-err-l85p61i4.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!
make[1]: *** [Makefile:55: html] Error 2
make[1]: Leaving directory '/home/build/Empirical/doc'
make: *** [Makefile:7: doc] Error 2

Could you please check if this is still an issue with the latest Sphinx/Breathe stack?

[jakobandersen]

The assertion is fixed in branch 1.7 of Sphinx now.

[vermeeren]

Great, I will try to reproduce again when Sphinx 1.7.6 is out.