Giter VIP home page Giter VIP logo

breathe's Introduction

Breathe

image

This is an extension to reStructuredText and Sphinx to be able to read and render the Doxygen xml output.

Download

Breathe is available from github and PyPI, the Python Package Index

Documentation

The documentation is available here. Thank you to the people running Read the Docs for such an excellent service.

The source for the documentation is in the documentation folder if you want to built it and read it locally.

Development

Breathe does not always get the attention it deserves but I am keen to keep it moving forward. If you report an issue, please keep reminding me about it until it is fixed. I should be better at this but in silence I tend to move to other things so keep reminding me.

Testing

Breathe doesn't have a set of tests at the moment. The documentation does a good job of running the different parts of the Breathe functionality but there is nothing to check that the output is appropriate.

To build the documentation, run make in the root of the project.

This will run doxygen over the example code and then run the Breathe documentation. View the results at:

documentation/build/html/index.html

Requirements

Development is currently done with:

  • Python 2.7.4
  • Docutils 0.11
  • Sphinx 1.2.2
  • Doxygen 1.8.4

Doxygen 1.5.1 seems to produce xml with repeated sections which causes Breathe some confusion. Not sure when this was resolved but it might be best to go for the latest possible.

Mailing List

There is a mailing list available on Google groups:

https://groups.google.com/forum/#!forum/sphinx-breathe

The previous mailing list was on librelist.com and the archives are available here.

Examples

Examples of Breathe used by other projects:

If you have an example you would like listed here, please make a github issue with the details.

Alternatives

Breathe is not the only solution to this problem. These are the alternatives that we know about. We are very happy to list others if you'd like to provide a link in a github issue or get in touch on the mailing list.

Credits

Breathe is maintained by michaeljones & vitaut with contributions from:

Thanks to:

  • Dimitri van Heesch for Doxygen.
  • Georg Brandl for Sphinx.
  • David Goodger for Docutils and reStructuredText.

Change Log

Inspired by Keepachangelog.com.

  • 2015-04-02 - Breathe v4.0.0
    • Significant work on the code base with miminal reStructureText interface changes. To be documented.
  • 2014-11-09 - Breathe v3.2.0
    • Nothing Added, Deprecated or Removed
    • Fixed
      • Changed docutils/Sphinx node usage to fix latex/pdf output.
      • When checking for path separators check for both / and \ regardless of the platform.
      • KeyError when using auto directives without specifying the :project: option even though the default project config setting was set.
      • Use of doxygenfunction no longer inappropriately triggers the duplicate target check and fails to output link targets.
      • Support for inline urls in the doxygen comments.
      • Support for array notation in function parameters.
      • Reduced intention by changing section-defs to use container & rubric nodes rather than desc nodes with signatures & content. Now headings like 'Public Functions' appear inline with their subject matter.
  • 2014-09-07 - Breathe v3.1.0
    • Nothing Deprecated or Removed
    • Added
      • The doxygenclass directive can now reference template specialisations by specifying the specialisation in the argument name.
    • Fixed
      • Displaying function parameters for Qt slots output. Previously they were missing even though Qt Slots are essentially just functions.
      • Displaying headings from doxygen comments as emphasized text.
      • Crash when generating warning about being unable to find a define, variable, enum, typedef or union.
      • Only output the definition name for a function parameter if the declartion name is not available. Previously, where they were both available we were getting two names next to each other for no good reason.
  • 2014-08-04 - Breathe v3.0.0
    • Improve output of const, volatile, virtual and pure-virtual keywords.
    • Fix css class output for HTML so that object types rather than names are output as the css classes. eg. 'function' instead of 'myFunction'.
    • Fix issue with Breathe getting confused over functions appearing in header and implementation files.
    • Improve matching for overloaded functions when using doxygenfunction directive. Also, provide a list of potential matches when no match is found.
    • Improved :members: implementation to handle inner classes properly.
    • Updated doxygenstruct to share the doxygenclass implementation path which grants it the options from doxygenclass directive.
    • Added :outline: option support to doxygengroup & doxygennamespace directives.
    • Added doxygennamespace directive.
    • Added :undoc-members: option to doxygenclass & doxygengroup directives.
    • Breaking change: Removed :sections: option for doxygenclass & doxygengroup directives and replaced it with :members:, :protected-members: and :private-members:, and changed breathe_default_sections config variable to breathe_default_members. This is designed to more closely match the Sphinx autodoc functionality and interface.
  • 2014-06-15 - Breathe v2.0.0
    • Add compare script for checking changes to documentation caused by changes in the implementation.
    • Switched to https reference for MathJax Javascript.
    • Breaking change: Change autodoxygen* directives to require explicitly declared source files in the conf.py rather than attempting to detect them from the directive arguments.
    • Switch documentation hosting to ReadTheDocs.org.
    • Breaking change: Switch to assuming all relative paths are relative to the directory holding the conf.py file. Previously, it would assume they were relative to the user's current working directory. This breaks projects which use separate build & source directories.
    • Add doxygenunion directive.
    • Add doxygengroup directive.
    • Add support for lists in the output. They were previously ignored.
    • Updated implementation to use the docutils nodes that Sphinx does where possible.
  • Breathe v1.2.0
    • Change log not recorded.

breathe's People

Watchers

 avatar  avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.