Bill, Great. Thank you.
Bob Nobis - N7RJN [email protected] > On Apr 29, 2015, at 04:49, Bill Somerville <[email protected]> wrote: > > Hi All, > > I have added steps to the build to generate the WSJT-X user guide > automatically. Currently this is working on a copy of the user guide > sources. This has been added as a proof of concept and IMHO it is > working correctly and provides several benefits over the current > arrangement with a separate documentation branch and build tools: > > 1) Documentation sources are held in the same VCS branch as the > application source code, therefore they are branched and tagged along > with the application source code they refer to, > 2) The build script injects asciidoc attributes for the current version > identification automatically, saving effort of routine editing tasks on > the documentation source for every release. Other attributes that the > the build script can generate can be easily added, > 3) The documentation generation works on all platforms, > 4) Developers and testers see the latest documentation when they make or > download a development build, > 5) The project web server can hold old versions of the documentation > which will be automatically referenced by the old version of WSJT-X, > this is facilitated by the generated document name being unique to the > version. > > With any new build component there may be a requirement for tools to be > installed, this is no exception as the user guide generation requires > the asciidoc tool and that itself requires a Python interpreter. For > *nix systems including Mac this is not a big issue as these can be > trivially installed on a build host system. On Windows there are a > couple of complications, as always :( Firstly the latest release of > asciidoc is broken and hangs on Windows, secondly as asciidoc does not > work with Python 3 there needs to be a way of doing builds on a Windows > build host that may well have both Python v2 and Python v3 installed. To > help with this I have set the build script to run asciidoc with a > specific Python interpreter located by an absolute path, this means that > even on a system where Pythion v3 is the default version, i.e. on the > PATH, the build will still work after a minor adjustment to your CMake > toolchain file. > > To try out the documentation build you need to checkout the development > branch ^/branches/wsjtx and make sure you have asciidoc and Python v2 > installed. On Windows you will need to download the latest snapshot of > asciidoc rather than the broken release version v8.6.9, this can be > fetched from https://github.com/asciidoc/asciidoc/archive/master.zip . > Unzip it somewhere and adjust your CMake tool chain file to add it to > the CMAKE_PREFIX_PATH variable. > > Currently the documentation generation is switched off unless you set > the CMake option WSJT_GENERATE_DOCS to ON in your build tree > configuration, if adopted this option would be ON by default. > > The only disadvantage I can see is that the documentation for the > various applications are no longer held in a single branch, but TBH I > believe this is actually an advantage and the single branch was more of > a solution to the problem of generation not being easy on some platforms > rather than providing any real benefit. Obviously the other applications > can maintain the current structure or move to a per application > documentation VCS and build. > > The implementation in the development branch is only a proof of concept > at this point, the actual documentation content is a copy of the WSJT-X > user guide sources with a few minor edits to take advantage of the new > features like automatic version number injection. If we decide to go > ahead with this change; I would delete the trial documentation sources > and move across the real sources in Subversion along with their full > history. This would require a small amount of coordination during the > switch over to ensure any in progress edits are not lost. > > I would also propose that this change is small enough in scope and > implications to merge into the WSJT-X branch for use in the impending > v1.5.0 release. > > 73 > Bill > G4WJS. > > ------------------------------------------------------------------------------ > One dashboard for servers and applications across Physical-Virtual-Cloud > Widest out-of-the-box monitoring support with 50+ applications > Performance metrics, stats and reports that give you Actionable Insights > Deep dive visibility with transaction tracing using APM Insight. > http://ad.doubleclick.net/ddm/clk/290420510;117567292;y > _______________________________________________ > wsjt-devel mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/wsjt-devel > ------------------------------------------------------------------------------ One dashboard for servers and applications across Physical-Virtual-Cloud Widest out-of-the-box monitoring support with 50+ applications Performance metrics, stats and reports that give you Actionable Insights Deep dive visibility with transaction tracing using APM Insight. http://ad.doubleclick.net/ddm/clk/290420510;117567292;y _______________________________________________ wsjt-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/wsjt-devel
