[Scons-dev] User-guide generation

[Dirk Bächle]

William,

On 19.08.2016 13:14, William Blevins wrote:
> Dirk,
>
> Apparently, the user guide data doesn't regenerate unless you call:
>
>         python bin/docs-update-generated.py
>         python bin/docs-validate.py
>         python bin/docs-create-example-outputs.py
>
> I guess it just doesn't make a lot of sense to me why these are manual steps rather than being commands that run as part of the
> #doc/user build step.
>

please have another look at

   https://bitbucket.org/scons/scons/wiki/DeveloperGuide/Documentation

. The normal user, only doing simple edits and changing text passages, shouldn't have to care about regenerating the output of the 
examples. He can run the validate script, and then compile the user guide for example, such that he gets an idea how the final 
PDF/HTML output might look like.
Everything beyond this point is in the scope of the actual release team. This separation is there to make it as easy as possible for 
new contributors to add or amend documentation. The required validation ensures that the checked in and merged doc changes by a user 
can be compiled into a correct document later on by a release manager, sort of justifying the usage of Docbook all together.

I hope this makes things a little clearer.

Finally, the UserGuide should also get recompiled when you change one of the chapter *.xml files. If this doesn't happen that would 
clearly qualify as a bug...

Best regards,

Dirk