Research and add Breathe docs to Readthedocs.org if possible

[michaeljones]

It is fast becoming the Python project default and would lead to more up to date docs if they are constantly rebuilt from the latest on the master branch rather than waiting for me to update them.

[remyleone]

👍 I think it would be handy to publish an example. I have a very large C project and it would really help me to have an example to look upon to make the complete workflow work (github + readthedocs + breathe) all together.

[michaeljones]

I was thinking originally of just getting the Breathe docs on to readthedocs but, yes, I would imagine that documenting the setup, if it is possible, would also help. It might depend on whether they have an up to date version of doxygen I guess. Unless people are in the habit of checking their doxygen xml into their git repositories which is not ideal.

Cheers for the thought!

[ahundt]

+1

[mikepurvis]

Having a canonical example of a workflow/config to get a Doxygen project onto RTD using Breathe would be tremendously helpful.

[vitaut]

👍 Looking forward to the Breathe on Read the Docs example too.

[michaeljones]

It is working and temporarily up at: http://breathe.readthedocs.org/en/readthedocs/

It is a build of the current readthedocs branch in which I've made a few changes to play nicely with RTD. I'll merge it in and try to make a page explaining what is needed over the next few days.

There were three main issues:

1. Read-the-docs finds the conf.py file and runs sphinx-build in that directory which is not how the Breathe docs are set up. The Breathe docs use separate source and build folders and work from a Makefile in the parent directory of the directory with conf.py. That means that all the relative paths in the Breathe docs failed to find there targets. To overcome this, I've changed the Makefile to cd into the source directory before running sphinx-build and then changed all the relative paths to work from there. I tried other work arounds but couldn't get them to work.
2. Read-the-docs does a fresh git clone which means that there are no doxygen xml files in the repository they are building from. To overcome this, we need to run doxygen before the build. I've chosen the most hacky way of achieving this for now which is to directly run cd & make commands in the conf.py if we detect we're on the RTD server. It is horrible but it seems to work.
3. The makefiles used which doxygen to find the path to the doxygen executable. For some reason this wasn't resolving on the RTD server so I switched it to being hard coded to doxygen so it picks up whatever version is on the PATH. I've no idea why the which doxygen didn't work. Maybe which isn't available for some strange reason. I've hard coded it for the moment, but we should have an if-statement to only hardcode it in the RTD environment.

Hope that helps a little,
Michael

[remyleone]

Do you think we could ask help to the rtd folks. I think it would be a game changer for them if they could easily host c documentation

—
Sent from Mailbox

On Thu, May 22, 2014 at 11:27 PM, Michael Jones notifications@github.com
wrote:

It is working and temporarily up at: http://breathe.readthedocs.org/en/readthedocs/
It is a build of the current readthedocs branch in which I've made a few changes to play nicely with RTD. I'll merge it in and try to make a page explaining what is needed over the next few days.
There were three main issues:

1. Read-the-docs finds the conf.py file and runs sphinx-build in that directory which is not how the Breathe docs are set up. The Breathe docs use separate source and build folders and work from a Makefile in the parent directory of the directory with conf.py. That means that all the relative paths in the Breathe docs failed to find there targets. To overcome this, I've changed the Makefile to cd into the source directory before running sphinx-build and then changed all the relative paths to work from there. I tried other work arounds but couldn't get them to work.
2. Read-the-docs does a fresh git clone which means that there are no doxygen xml files in the repository they are building from. To overcome this, we need to run doxygen before the build. I've chosen the most hacky way of achieving this for now which is to directly run cd & make commands in the conf.py if we detect we're on the RTD server. It is horrible but it seems to work.
3. The makefiles used which doxygen to find the path to the doxygen executable. For some reason this wasn't resolving on the RTD server so I switched it to being hard coded to doxygen so it picks up whatever version is on the PATH. I've no idea why the which doxygen didn't work. Maybe which isn't available for some strange reason. I've hard coded it for the moment, but we should have an if-statement to only hardcode it in the RTD environment.
   Hope that helps a little,

Michael

Reply to this email directly or view it on GitHub:
#89 (comment)

[michaeljones]

Hi,

What aspect of the setup would you have them change or support? What would you ask them?

Cheers,
Michael

[remyleone]

I would ask them to review the code and the general process I think breathe
could really interest them.

2014-05-23 11:33 GMT+02:00 Michael Jones notifications@github.com:

Hi,

What aspect of the setup would you have them change or support? What would
you ask them?

Cheers,
Michael

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/89#issuecomment-43988950
.

[michaeljones]

Hi,

I think it is reasonable that we change Breathe so that all the paths that the user provides are assumed to be relative to the conf.py directory. This will be a breaking change for some set ups (including the Breathe documentation) but I think that represents more idiomatic Sphinx plugin style.

It will also smooth the transition to putting stuff on ReadTheDocs as it will fit with their model.

Otherwise, I feel that it is fairly easy to get Breathe running on ReadTheDocs given that doxygen needs to be run and it is not hard to do so.

I encourage you to raise issues and talk with them if you feel that the workflow could be better but I don't really see how it could be significantly improved without special casing Breathe and I'm afraid I don't want to encourage that level of dependence on Breathe as I don't want to be locked into any particular behaviours.

I will make the adjustments to Breathe and include help on getting Sphinx documentation that uses Breathe on to ReadTheDocs.

Cheers,
Michael

[remyleone]

I think this link could be useful to keep in mind :
readthedocs/readthedocs.org#125
readthedocs/readthedocs.org#388

2014-05-25 21:35 GMT+02:00 Michael Jones notifications@github.com:

Hi,

I think it is reasonable that we change Breathe so that all the paths that
the user provides are assumed to be relative to the conf.py directory. This
will be a breaking change for some set ups (including the Breathe
documentation) but I think that represents more idiomatic Sphinx plugin
style.

It will also smooth the transition to putting stuff on ReadTheDocs as it
will fit with their model.

Otherwise, I feel that it is fairly easy to get Breathe running on
ReadTheDocs given that doxygen needs to be run and it is not hard to do so.

I encourage you to raise issues and talk with them if you feel that the
workflow could be better but I don't really see how it could be
significantly improved without special casing Breathe and I'm afraid I
don't want to encourage that level of dependence on Breathe as I don't want
to be locked into any particular behaviours.

Cheers,
Michael

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/89#issuecomment-44143433
.

[michaeljones]

I've just posted over on that issue as my tests on RTD have started failing. Hopefully they know what can be done about it.

Also, I came across this: https://github.com/Cruel/readthedocs-breathe which might be of some use.

Cheers,
Michael

[michaeljones]

The RTD guys fixed the issue in record time. Looks like they are committed to having doxygen installed on the servers so all is well.

Breathe docs are built and up here: http://breathe.readthedocs.org/en/latest/

My first attempt at a "getting Breathe on ReadTheDocs" help page is here: http://breathe.readthedocs.org/en/latest/readthedocs.html

[remyleone]

From the python documentation :

os.system(command)

The subprocess module provides more powerful facilities for spawning new
processes and retrieving their results; using that module is preferable to
using this function. See the Replacing Older Functions with the subprocess
Module section in the subprocess documentation for some helpful recipes.

Availability: Unix, Windows.

[michaeljones]

Cheers for the feedback. I've pushed a new version here: http://breathe.readthedocs.org/en/readthedocs/readthedocs.html

Hopefully that seems more appropriate.

[michaeljones]

I'm going to close this for the moment. Please reopen if there are additional suggestions.

[svenevs]

Hi @michaeljones, thanks for breathe :) I was trying to figure out how all of the pieces fit together (doxygen, sphinx, breathe, readthedocs, etc.) and finally found this post. I think it would be really useful if you add the example repo you found: https://github.com/Cruel/readthedocs-breathe . It would probably be enough to link it at at the bottom of http://breathe.readthedocs.org/en/readthedocs/readthedocs.html ?

The sphinx build process explicitly lists doxygen as of this time, but not breathe. My understanding (through failure) is that I am missing

1. Not using a separate source and build, and that seems to break on RTD.
2. In order to include 'breathe' in the extensions list in conf.py you need the related line in requirements.txt.

Both of which were described on this thread. Though excellent, the RTD docs are somewhat vague about what is called when. My project uses CMake and having a setup.py in the root directory would be misleading / not as nice. I still don't have things working, but I suspect that repo's strategy is valid and I think it would be good to link to it from your breathe RTD.