Hello All, For some time now, I've been looking for a better ( easier ) way of managing release documentation, and I think I have a solution that meets all the needs I have ( maybe others ), and thought I'd pass this along. I still use AsciiDoctor, Allot, but I am finding this solution to be easier and faster for software related stuff.
I've migrated most of the JTSDK source code over to GitHub ( SF will still be used for large file storage / archive ) and have started using "Read The Docs" for automated online documentation generation. Example ( sill a work in progress ): http://jtsdk-win.readthedocs.io Long story short, the process uses Sphinx reST ( Restructured Text ) and a GitHub hook to push the source code whenever a commit hits the Master branch. Basically, I don't have to do anything, other than ensure the docs are ready to go before code is pushed to the master branch. RTD ( Read The Docs ) generates three file formats ( HTML, PDF and EPUB ) for every update. Local Sphinx installations can build some 15 or so formats, including Manpages and *does not* require AsciiDoc / A2X nor any of the XML related libraries. Sphinx will work with Python2 or Python3, it matters not which one. I used pip in a Virtual Environment to install Sphinx + Dependencies, it took less than 1 minute start to finish, with no affect on Main System Packaging ( nothing installed outside of my $USER ). If you use the Sphinx Autobuilder ( sphinx-autobuild ), it will create a Makefile and / or Make.bat file for you. It asks all the questions, you just fill in the blanks when asked, at the end, you have the start of a project you can now work on / add too / test build with or whatever. To build the docs, simply change directories to the docs dir you ran sphinx-autobuilder in and: #---------- make html make epub make clean etc etc #---------- The entire virtual environment, including Python + all of it's base requirements, was about ~61 MB, without LaTeX. Adding in LaTeX adds a fare bit more, but nothing major. The install process is very simple: In A Terminal #--------------------------------------------------- mkvirtualenv -p python=python3 jtsdk-win workon jtsdk-win pip install sphinx sphinx-autobuild sphinx-rtd-theme #--------------------------------------------------- Thats it. Now you have a Python3 Virtual environment with Sphinx and all the required packaging to build your documentation ( without messing with your system packaging ). Any time you want to exit the Python3 Env, simply type: deactivate, and your back to your normal Python Environment. On Linux, you can install all the packages with the system package manager if you don't need to use Virtual Envs for isolation. I like to use them for insurance. Anyway, checkout Sphinx + reST ( Restructured Text ), it is simple to setup / use, builds lots of doc types easily, and can be run without affecting base system packaging. 73's Greg, KI7MT ------------------------------------------------------------------------------ What NetFlow Analyzer can do for you? Monitors network bandwidth and traffic patterns at an interface-level. Reveals which users, apps, and protocols are consuming the most bandwidth. Provides multi-vendor support for NetFlow, J-Flow, sFlow and other flows. Make informed decisions using capacity planning reports. https://ad.doubleclick.net/ddm/clk/305295220;132659582;e _______________________________________________ wsjt-devel mailing list wsjt-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/wsjt-devel
