rmcgibbo / sphinxcontrib-autodoc_doxygen Goto Github PK

View Code? Open in Web Editor NEW

15.0 3.0 5.0 696 KB

Sphinx / Doxygen bridge

License: MIT License

Python 100.00%

sphinxcontrib-autodoc_doxygen's Introduction

sphinxcontrib-autodoc_doxygen

Example Output

This a (pre-alpha) extension for sphinx that to read and display Doxygen XML output. It is similar to Breathe. The implementation extends sphinx.ext.autodoc and sphinx.ext.autosummary as closely as possble.

Usage

In your Sphinx conf.py add 'sphinxcontrib.autodoc_doxygen' to the list of extensions, and set the variable doxygen_xml to a string containing the path to the directory containing your Doxygen XML output.

This adds the following RST directives.

autodoxysummary
autodoxyclass
autodoxymethod
autodoxyenum

Examples

.. autodoxysummary::
   :toctree: generated/
   :template: doxyclass.rst

   OpenMM::CustomIntegrator
   OpenMM::CustomCompoundBondForce

This produces the output shown here

Installation

You can install it with pip (py27 or py33+):

pip install sphinxcontrib-autodoc_doxygen

The necessary dependences should be grabbed by pip. If you have trouble getting lxml, here are some tips:

If you use the Anaconda Python distribution, run conda install lxml. With the system package manager on linux, sudo apt-get install python-lxml or sudo yum install python-lxml should do the trick. On Windows, you may be able to download the lxml from Christoph Gohlke's repository. On OS X, try the following long command brew install libxslt libxml2; LDFLAGS="-L/usr/local/opt/libxslt/lib -L/usr/local/opt/libxml2/lib" CPPFLAGS="-I/usr/local/opt/libxml2/include -I/usr/local/opt/libxslt/include" pip install lxml. It may take a long time (~5 minutes), but once the wheel is built, it will be cache, so you only need to do this once, even if switch virtualenvs.

sphinxcontrib-autodoc_doxygen's People

Contributors

Stargazers

Watchers

Forkers

shibukawa peastman angus-g jr3cermak 0phoff

sphinxcontrib-autodoc_doxygen's Issues

C# compatibility

Is this compatible with C# xml output from doxygen?

I tried on a project and can't figure out the error. Ironically, the project doesn't have documentation :).

I have the xml folder with an index.rst containing the c# class name and reference to the .xml file for that class. When I use the xml name with autodoxysummary, the sphinx output just gives a Warning [autosummary] failed to import 'namespace::classname' where namespace::classname is between the <name></name> tags in index.xml.

Is this incorrect use?

Create release that works with modern Sphinx

The latest pypi release specifies the requirement Sphinx==1.5. That's now a very old version, and many other sphinxcontrib packages aren't compatible with it. Could you create a new pypi release that works with the current version of Sphinx?

Omit namespace and class from method names

I did this by changing line 134 of autodoc.py from

return (rtype and (rtype + ' ') or '') + self.modname + '::' + self.objpath

return (rtype and (rtype + ' ') or '') + self.objpath

You mentioned before that this caused links to methods to be broken, but as far as I can tell it seems to work fine.

By the way, all the examples at https://rawgit.com/rmcgibbo/sphinxcontrib-autodoc_doxygen/gh-pages/autodoxyclass.html include the option :members:. When I include that, I get the error message

ERROR: An option to autodoxyclass is either unknown or has an invalid value: 'members'

If I omit it, everything seems to work correctly.

autodoxysummary error with anonymous enums

When a class has an anonymous enum, autodoxysummary produces an error when reading the generated rst file. Here is the error:

reading sources... [ 50%] generated/MyA                                                                                                                                                                            
Exception occurred:
  File "/home/user/.local/lib/python3.6/site-packages/sphinxcontrib/autodoc_doxygen/autosummary/__init__.py", line 208, in get_items
    self.name = names[0]
IndexError: list index out of range

I guess the autodoxysummary tries to get the name from this object.

Here is a minimal example:

/** Test MyA class */
class MyA {
    public:
        enum {V1, ///< Value 1
              V2, ///< Value 2
              V3  ///< Value 3
        };
};

With the following directive:

.. autodoxysummary::
    :toctree: generated/

    MyA

Here is the generated rst file:

MyA
===

.. autodoxyclass:: MyA
   :members:

   .. autodoxyenum:: @0

Finally, here is the xml generated by Doxygen:

<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.8.13">
  <compounddef id="classMyA" kind="class" language="C++" prot="public">
    <compoundname>MyA</compoundname>
    <includes refid="testEnum_8h" local="no">testEnum.h</includes>
      <sectiondef kind="public-type">
      <memberdef kind="enum" id="classMyA_1a7bcfd27036500c2686bb5175749d0343" prot="public" static="no">
        <name>@0</name>
        <enumvalue id="classMyA_1a7bcfd27036500c2686bb5175749d0343abdc64aab6da9f04d44f0cb3850a5c8dd" prot="public">
          <name>V1</name>
          <briefdescription>
<para>Value 1. </para>          </briefdescription>
          <detaileddescription>
          </detaileddescription>
        </enumvalue>
        <enumvalue id="classMyA_1a7bcfd27036500c2686bb5175749d0343aa78afe20d1b1ecf0a03b19fec80989cf" prot="public">
          <name>V2</name>
          <briefdescription>
<para>Value 2. </para>          </briefdescription>
          <detaileddescription>
          </detaileddescription>
        </enumvalue>
        <enumvalue id="classMyA_1a7bcfd27036500c2686bb5175749d0343a195f5c9f585d2ea5a70514706d8e2653" prot="public">
          <name>V3</name>
          <briefdescription>
<para>Value 3. </para>          </briefdescription>
          <detaileddescription>
          </detaileddescription>
        </enumvalue>
        <briefdescription>
        </briefdescription>
        <detaileddescription>
        </detaileddescription>
        <inbodydescription>
        </inbodydescription>
        <location file="testEnum.h" line="8" column="1" bodyfile="testEnum.h" bodystart="8" bodyend="11"/>
      </memberdef>
      </sectiondef>
    <briefdescription>
    </briefdescription>
    <detaileddescription>
<para>Test <ref refid="classMyA" kindref="compound">MyA</ref> class </para>    </detaileddescription>
    <location file="testEnum.h" line="5" column="1" bodyfile="testEnum.h" bodystart="5" bodyend="15"/>
    <listofallmembers>
      <member refid="classMyA_1a7bcfd27036500c2686bb5175749d0343abdc64aab6da9f04d44f0cb3850a5c8dd" prot="public" virt="non-virtual"><scope>MyA</scope><name>V1</name></member>
      <member refid="classMyA_1a7bcfd27036500c2686bb5175749d0343aa78afe20d1b1ecf0a03b19fec80989cf" prot="public" virt="non-virtual"><scope>MyA</scope><name>V2</name></member>
      <member refid="classMyA_1a7bcfd27036500c2686bb5175749d0343a195f5c9f585d2ea5a70514706d8e2653" prot="public" virt="non-virtual"><scope>MyA</scope><name>V3</name></member>
    </listofallmembers>
  </compounddef>
</doxygen>

Thanks for your project!

rmcgibbo / sphinxcontrib-autodoc_doxygen Goto Github PK

sphinxcontrib-autodoc_doxygen's Introduction

sphinxcontrib-autodoc_doxygen

Usage

Examples

Installation

sphinxcontrib-autodoc_doxygen's People

Contributors

Stargazers

Watchers

Forkers

sphinxcontrib-autodoc_doxygen's Issues

C# compatibility

Create release that works with modern Sphinx

Omit namespace and class from method names

autodoxysummary error with anonymous enums

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent