Dirk, Inline...
On Fri, Aug 19, 2016 at 10:45 PM, Dirk Bächle <tshor...@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@scons.org > https://pairlist2.pair.net/mailman/listinfo/scons-dev >
_______________________________________________ Scons-dev mailing list Scons-dev@scons.org https://pairlist2.pair.net/mailman/listinfo/scons-dev