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

[Björn Pollex]

Thanks for the reply, I will consider your advice. For the moment, the
tools are intended for internal use only. I generally prefer to write
documentation in the code, and not in separate files, but that does not
seem to be an option in SCons.

Are there any plans or ideas to add a standard help or documentation
mechanism to SCons? Something like:

env.Help(SomeBuilderName)

That would return a String with documentation about that builder. Such a
mechanism could also be made to work with construction variables. When
importing SCons into an interactive interpreter, this could be used as an
interactive help system.

Has this ever been discussed? If there is interest (or at least no
objections), I could investigate how to build something like this.

Regards,

Björn

P.S.: I tried adding SCons to the PYTHONPATH and importing it, and it seems
to work (to the extend that this makes sense, for instance for inspecting
environments). Is this an official feature? Is this documented somewhere?
It would be interesting to investigate how this could be used for
interactive build-script development.


On Thu, Mar 20, 2014 at 6:52 PM, Dirk Bächle <tshortik at gmx.de> wrote:


> 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

>

>

> _______________________________________________

> Scons-users mailing list

> Scons-users at scons.org

> http://four.pairlist.net/mailman/listinfo/scons-users

>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://four.pairlist.net/pipermail/scons-users/attachments/20140322/5badf663/attachment.html