Skip to content
Branch: master
Go to file

Latest commit


Failed to load latest commit information.
Latest commit message
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.


Sphinx version > 1.0

From source (tar.gz or checkout)

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

python install


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 and any input is welcome.

Enabling the extension in Sphinx

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

extensions = ['sphinxcontrib.cmtinc']


.. 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-block:: c

      Comment for the following code block

      .. code-block:: c

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.


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


The same as the Include Directive of Sphinx (


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


Include comments form source files extension for sphinx-doc




No releases published


You can’t perform that action at this time.