[Scons-dev] User-guide generation

[William Blevins]

Dirk,

Inline...

On Fri, Aug 19, 2016 at 10:45 PM, Dirk Bächle <tshortik at gmx.de> wrote:

> 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


Right and I understand that there is documentation, and I use it when I
have an issue. The problem that I have is that I have worked with the docs
more than most (outside the maintainer team), and I always seem to forget
about the #bin scripts. In my opinion, a good process is intuitive and
doesn't have lots of manual steps. I think it would be a good idea to have
the SConstruct in #doc/user to Execute the #bin scripts in order. I don't
think it would cause any issues, but would make generating the docs a
1-step process. Is there a reason not to do something like this?


>
>
> . 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 don't see the harm in a regular developer getting a generated document
that reflects the changes made. If I make changes to documents and
regenerating the user guide doesn't show my changes, then it gets very
puzzling.


>
> 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...
>

It rebuilds. We may want to change the wiki documentation though, because
python-lxml does not appear to work correctly with the chunked guides
index.html. I moved to python-libxml2 and python-libxslt1 and that seemed
to make things happier.


>
> Best regards,
>
> Dirk
>
>
> _______________________________________________
> Scons-dev mailing list
> Scons-dev at scons.org
> https://pairlist2.pair.net/mailman/listinfo/scons-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://pairlist2.pair.net/pipermail/scons-dev/attachments/20160819/3d0d125f/attachment-0001.html>