# w-vi / sphinxcontrib-cmtinc

Include comments form source files extension for sphinx-doc

## Files

Failed to load latest commit information.
Type
Name
Commit time

# Include comments from source files extension for Sphinx

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.

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>.

/**
.. 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.

Include comments form source files extension for sphinx-doc