Hi all,
I recently started using Sphinx for documenting my very heterogeneous
(but almost totally non-python) project. What I was missing was a way to
extract documentation elements from (non python) source files. So I came
up with a following approach with worked out beautifully for me:
I have added a new directive called 'autoextract'. It has no content
and has two parametes - a source file, and a documentation element tag.
How it works is best described with a simple example:
<documentation.txt>
.. autoextract:: ../Sources/myFile.cpp myCoolFuncDocTag
</documentation.txt>
<../Sources/myFile.cpp>
// autoextract::begin myCoolFuncDocTag
//
// .. c:func:: void myCoolFunc( int x )
//
// Some myCoolFunc documentation.
//
// autoextract::end
void myCoolFunc( int x )
{
....
}
</../Sources/myFile.cpp>
When generating documentation all the data between autoextract::begin
and autoextract::end is embedded in the documentation.txt file,
similarly to include directive. The comment prefixes are removed, so I
get equivalent of:
<documentation.txt>
.. c:func:: void myCoolFunc( int x )
Some myCoolFunc documentation.
</documentation.txt>
This approach makes it easier to keep implementation in sync with the
documentation, as I only need to update the comment above the function
implementation directly in the source file. It is a real life saver if
you use Sphinx for non-python project.
If there is any interest, I can upload my autoextract module to
contributions (it is quite simple really, ~100 LOC, although I have a
few ideas to make it more complicated ;) ).
Of course, it is quite possible that Sphinx somehow already supports
this and I just missed it. If so please point me in the right direction.
And thank you all for the awesome documentation tool!
Best Regards,
Juraj Ivančić
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en.
