librelist archives

« back to archive

Fwd: [sphinx-dev] Sphinx, Breathe and C projects

Fwd: [sphinx-dev] Sphinx, Breathe and C projects

From:
Michael Jones
Date:
2011-03-27 @ 03:26
Testing Breathe list.


---------- Forwarded message ----------
From: Michael Jones <m.pricejones@gmail.com>
Date: Sun, Mar 27, 2011 at 3:17 PM
Subject: Re: [sphinx-dev] Sphinx, Breathe and C projects
To: Diego Escalona <erdadi@gmail.com>
Cc: Breathe <breathe@librelist.com>


Hi Diego,

I've pushed some basic support for a "doxygenfile" directive with some
docs to explain it a little. It is unfortunately far from perfect but
I wanted to keep you up to date.

One particular issue that I am aware of, this that is lists "structs"
as classes. I need to take a bit of a different approach to correct
this so I probably won't get around to it before next weekend.

I'd be very grateful if you could give it a go though and let me know
if you encounter other issues which I could correct.

Thanks
Michael


On Tue, Mar 22, 2011 at 7:11 AM, Diego Escalona <erdadi@gmail.com> wrote:
> 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!
>
> On Mon, Mar 21, 2011 at 7:02 PM, Michael Jones <m.pricejones@gmail.com>
> wrote:
>>
>> 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
>>
>>
>> On Tue, Mar 22, 2011 at 5:32 AM, Diego Escalona <erdadi@gmail.com> wrote:
>> > 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!
>> >
>> > --
>> > You received this message because you are subscribed to the Google
>> > Groups
>> > "sphinx-dev" group.
>> > To post to this group, send email to sphinx-dev@googlegroups.com.
>> > To unsubscribe from this group, send email to
>> > sphinx-dev+unsubscribe@googlegroups.com.
>> > For more options, visit this group at
>> > http://groups.google.com/group/sphinx-dev?hl=en.
>> >
>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "sphinx-dev" group.
>> To post to this group, send email to sphinx-dev@googlegroups.com.
>> To unsubscribe from this group, send email to
>> sphinx-dev+unsubscribe@googlegroups.com.
>> For more options, visit this group at
>> http://groups.google.com/group/sphinx-dev?hl=en.
>>
>
> --
> You received this message because you are subscribed to the Google Groups
> "sphinx-dev" group.
> To post to this group, send email to sphinx-dev@googlegroups.com.
> To unsubscribe from this group, send email to
> sphinx-dev+unsubscribe@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/sphinx-dev?hl=en.
>