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
