[Scons-users] How to generate and distribute documentation for a custom tool?

[Dirk Bächle]

Hi Björn,

On 20.03.2014 09:31, Björn Pollex wrote:

> I am currently trying to figure out how to best document a set of 

> custom SCons tools I have written. I would like some way to write 

> documentation in the source-code and then extract that using some 

> documentation generation tool.

>


as far as I know, you can also have *.rst files next to your Python 
modules. They can then be added to the index.rst (TOC) and get picked up 
during the following run of Sphinx. Here I'm assuming that your question 
is more about documentation like a manual for the user, explaining how 
to setup the Tool, remarks, warnings...whatever.

If you plan to get your Tools in the SCons core later on, you might want 
to stick to DocBook straight away...because that'll be the required 
format if you want your Builders to appear in the User Guide 
automatically. Just bear that in mind, it might save you some work later. ;)


> One problem is that several Python documentation generation tools 

> (e.g. Sphinx) will try to import the modules from which they extract 

> documentation. This naturally won't work for SCons.

>


This probably happens because you use some extension/plugin like 
"sphinx-apidoc", right? You don't have to do that...see my comment above.

Hope this helps you a little further.

Best regards,

Dirk