w-vi / sphinxcontrib-cmtinc

Include comments form source files extension for sphinx-doc

Include comments from source files extension for Sphinx

About

This extension allows to extract valid Sphinx formatted comments from source files. It extracts any comment starting with /** double star as is usual with (java/js/doxygen) doc style comments. It goes through the whole file and grabs whatever valid comment it finds.

This extension adds the include-comment directive that automatically extracts the comments and creates valid entries for the Sphinx writer used to generate the documentation.

You can see the latest documentation at the sphinxcontrib-cmtinc website.

Download

You can see all the available versions at PyPI.

Requirements

Sphinx version > 1.0

From source (tar.gz or checkout)

Unpack the archive, enter the sphinxcontrib-comment-icnlude directory and run:

python setup.py install

Setuptools/PyPI

Alternatively it can be installed from PyPI, either manually downloading the files and installing as described above or using:

easy_install -U sphinxcontrib-cmtinc

Directly from Git repo

Of course it is also possible to build it directly from the source. The git repo is hosted on https://github.com/w-vi/sphinxcontrib-cmtinc and any input is welcome.

Enabling the extension in Sphinx

Just add sphinxcontrib.cmtinc to the list of extensions in the conf.py file. For example:

extensions = ['sphinxcontrib.cmtinc']

Usage

.. include-comment:: <file>

This will extract any comments starting with /** in the file <file>.

Example c header.h

/**
  .. c:type:: my_struct_t

  This is a struct for holding values.
*/
typedef struct my_struct_s
{
    int id;
    struct timeval t;
    void *value;
 }  my_struct_t;

/**
 .. c:function:: my_struct_t * connect(my_struct_t * m, const char *url)

 Connect the client to the server given by *url*.

*/
my_struct_t * connect(my_struct_t * m, const char *url);

And to include whole code blocks without retyping them you may use the following syntax:

  /**
    Comment for the following code block

    .. code-block:: c

    \code
  */
  code_to_showcase();
  /**
    \endcode
  */

or

.. code-block:: c


    /**
      Comment for the following code block

      .. code-block:: c
      \multicomment
    */
    code_to_showcase();
    /**
      \end_multicomment
    */

Every comment block "/** ... */" will be suffixed with a new line.

If you do whish to have a more direct control over the identation you may use the * character as virtual line start

/**
  This line will be on root level
 *  this line has a identation of 2
*/

If you do want to keep the identation of your comments as is you may use the \toggle_keepwhitespaces command in your included file.

Result:

.. include-comment:: ../README.rst

Configuration

The same as the Include Directive of Sphinx (http://docutils.sourceforge.net/docs/ref/rst/directives.html#include)

TODO

• Enable inclusion of just selected comments, what I see as usefull is gathering same type objects so it'd be for example possible to firts list data types and then functions.
• Enable signature creation form the source. (Lexers are already in place.)
• Transform the doxygen and other styles to Sphinx rst.

copyright:	Copyright 2014 by Vilibald W.
license:	BSD, see LICENSE.txt for details.

sphinxcontrib-cmtinc's Issues

Text generated by cmtinc is indented one level

If I use the directive as suggested in http://pythonhosted.org/sphinxcontrib-cmtinc/ the resulting text is indented by one level.

The following code:

            if m:
                self.content.append("    " + m.group(1).strip(), "comment")
                continue

can be altered to "fix" the issue by removing the quoted string of spaces at the beginning of the appended text.

But rather than applying this patch, I would like to ask if there is a specific reason for adding the quoted spaces? Would it be another option to add a prepending string as an option to the directive?