Sphinx, Breathe and C projects

[Diego Escalona]

Hello everybody.

I don't know if this is the correct place to ask the question, but I'll try :)

I have documented a couple of projects made in Python, but now I have one written in C. Reading the Sphinx doc I have seen that Sphinx supports C directives, which is very interesting as it would make possible to document my C project in Sphinx.

To create the API reference of my Python projects, I have a script that generates the corresponding rst file for each python module and the index.rst file for each folder. Then, building the project in Sphinx I obtain the API reference for all my Python modules in an easy and beautiful way including the index of each folder.

My problem now is that I would like to do something similar with my C project. It is, I would like to automatically create an rst file for each C and H file and the index file for each folder. Reading over internet I found a project called Breathe which links Doxygen with Sphinx. I have tried it but the result I have obtained is not as good as I expected. It lists the contents of all the c files which compose my project in the same page and it doesn't generate the general main index nor the module index page. BTW, the Breathe directive I use is this (filling it with my project details):

.. doxygenindex::
   :project: ...
   :path: ..

But as said, it creates a file displaying the contents of every C file one after another.


So, my question is... Does Breathe has any kind of script to create the rst file of each C and H file? Or... how could I create such kind of script? I would like to have separate rst files for each C files and maintain the folder structure of my project...


Thanks all!

[Michael Jones]

Hi Diego,

Thanks for taking the time and trying Breathe.

You've unfortunately identified a weakness with the Breathe extension
at the moment. It would be great to have an equivalent of
sphinx-autogen to create the appropriate rst files for a C or C++
project. This hasn't been done yet unfortunately. The good news is
that it shouldn't be too hard, the bad news is it'll be a week or so
before I can get around to doing it.

Additionally it would be useful to implement a doxygenfile directive
which might simplify your request as the autogen script wouldn't have
to specify every function and struct it comes across. The doxygenindex
directive you have tried is honestly not that useful except for very
small projects and the breathe documentation.

If you'd be interested in contributing, I'd be very happy to advise on
how to approach these issues.

Cheers,
Michael

> --
> You received this message because you are subscribed to the Google Groups
> "sphinx-dev" group.
> To post to this group, send email to sphin...@googlegroups.com.
> To unsubscribe from this group, send email to
> sphinx-dev+...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/sphinx-dev?hl=en.
>

[Diego Escalona]

Hello Michael, thank you so much for your answer!

First of all, I must thank you for your work, it is really what I was looking for to document my C project :)

About the doxygenfile directive, it would definitely address my problem, because I could just develop a simple Python script to generate all the necessary rst files and index including inside the doxygenfile directive with the corresponding file of the project.

I'll stay tuned, keep on with the good work!

Thanks!

[Sushant Hiray]

Hey Michael,

I was just trying out Breathe for a small project and I seem to hit the same roadblock.

Is the forementioned feature added in breathe?

If it is, could you give me some pointers regarding it.

If not I would be happy to help adding it.

Regards,

Sushant