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.
From source (tar.gz or checkout)¶
Unpack the archive, enter the sphinxcontrib-cmtinc 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://bitbucket.org/wvi/sphinxcontrib-cmtinc and any input is welcome.
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);
- my_struct_t¶
This is a struct for holding values.
- my_struct_t * connect(my_struct_t * m, const char *url)¶
Connect the client to the server given by url.
Configuration¶
None so far.
TODO¶
- Enable inclusion of just selected comments, what I see as useful is gathering same type objects so it’d be for example possible to first 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 for details. |
ChangeLog¶
This file describes user-visible changes between the extension versions.
Version 0.1 (2014-04-20)¶
- Initial version.
License¶
BSD License
Copyright (c) 2014 Vilibald Wanča <vilibald (at) wvi (.) cz>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.