Hi Bill, Thanks for the update / info.
A couple things to note. * The current method of build is linked, meaning, the images, JS and CSS is shared and not embedded into a single HTML file (data-uri). I don't know if you plan on adding the data-uri method of build or not but it is handy to have, as it removes any relative path problems for Images and icons. * On Windows, due to several GNU dependencies (liboostboost-regex) that cannot easily be met, you cannot use source-highlight in the documentation source files. You can use Python Pygments, but you'd need to add the Pygments module into your Python2 installation and Generate the Pygments filter, then set the default highlight in asciidoc.conf to Pygments. The default highlighter is source-highlight. * I working on an update to JTSDK-Win32 to add everything to build the docs, but it's going to take a while. This will also remove the Cyg32 install, which was useful for more than just docs. I'm not sure how Joe wants to handle all the other documentation yet, so will need some guidance there. 73's Greg, KI7MT On 04/29/2015 05:49 AM, Bill Somerville 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 > -- ---------------------------------------------------------------- Launchpad....: https://launchpad.net/~ki7mt Ubuntu Hams..: https://launchpad.net/~ubuntu-hams-devel Debian Hams..: https://alioth.debian.org/projects/pkg-hamradio/ JTSDK........: https://sourceforge.net/projects/jtsdk/ OpenPGP......: C177 6630 7115 78FE 9A2B 9F7F 18C0 F6B7 0DA2 F991 ------------------------------------------------------------------------------ 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
