Merge branch 'ford' of https://github.com/jacobwilliams/json-fortran

Author: jacobwilliams

.gitignore

@@ -1,6 +1,7 @@
 bin/
 lib/
 builds/
+doc/
 *.mod
 *.o
 *.obj

.travis.yml

@@ -12,10 +12,10 @@ env:
       # CMake build with unit tests, no documentation, with coverage analysis
       # No unicode so that coverage combined with the build script will cover unicode
       # and non-unicode code paths
-    - BUILD_SCRIPT="mkdir cmake-build && cd cmake-build && cmake -DSKIP_DOC_GEN:BOOL=TRUE -DCMAKE_BUILD_TYPE=COVERAGE .. && make -j 4 check"
+    - BUILD_SCRIPT="mkdir cmake-build && cd cmake-build && cmake -DCMAKE_BUILD_TYPE=COVERAGE .. && make -j 4 check"
       SPECIFIC_DEPENDS="cmake nodejs"
       JLINT="yes"
-      DOCS="no"
+      DOCS="yes"
       FoBiS="no"
       CODE_COVERAGE="yes"
 
@@ -41,7 +41,6 @@ before_install:
   - if [[ $JLINT == [yY]* ]]; then curl -sL https://deb.nodesource.com/setup | sudo bash -x - ; fi
   - if [[ $CHECK_README_PROGS == [yY]* ]]; then wget http://people.sc.fsu.edu/~jburkardt/f_src/f90split/f90split.f90; fi
   - if [[ $DOCS == [yY]* ]]; then export DEPENDS="$DEPENDS exuberant-ctags"; fi
-  - if [[ $DOCS == [yY]* ]]; then wget http://launchpadlibrarian.net/70968359/robodoc_4.99.41-1_amd64.deb; fi
   - ulimit -s unlimited
 
 install:
@@ -50,7 +49,7 @@ install:
   - sudo ln -fs /usr/bin/gfortran-4.9 /usr/bin/gfortran && gfortran --version
   - sudo ln -fs /usr/bin/gcov-4.9 /usr/bin/gcov && gcov --version
   - if [[ $FoBiS == [yY]* ]]; then sudo -H pip install FoBiS.py && FoBiS.py --version; fi
-  - if [[ $DOCS == [yY]* ]]; then sudo dpkg -i robodoc_4.99.41-1_amd64.deb && robodoc --version; fi
+  - if [[ $DOCS == [yY]* ]]; then sudo -H pip install ford && ford --version; fi
   - if [[ $CHECK_README_PROGS == [yY]* ]]; then gfortran -o f90split f90split.f90 && ./f90split README.md && shopt -s extglob && for f in !(README|CONTRIBUTING|CHANGELOG).md; do mv $f src/tests/jf_test_${f%.md}.f90; done; rm f90split.f90 f90split; fi
 
 script:
@@ -62,4 +61,4 @@ after_success:
   - if [[ $CODE_COVERAGE == [yY]* ]]; then bash <(curl -s https://codecov.io/bash) ; fi
   - git config --global user.name "TRAVIS-CI-for-$(git --no-pager show -s --format='%cn' $TRAVIS_COMMIT)"
   - git config --global user.email "$(git --no-pager show -s --format='%ce' $TRAVIS_COMMIT)"
-  - ./deploy.sh #handles updating documentation for master branch as well as tags
+#broken for now#  - ./deploy.sh #handles updating documentation for master branch as well as tags

CMakeLists.txt

@@ -138,41 +138,46 @@ set_target_properties ( ${LIB_NAME}
   Fortran_MODULE_DIRECTORY ${CMAKE_BINARY_DIR} )
 
 #-------------------------------------
-# Build the documentation with ROBODoc
+# Build the documentation with FORD
 #-------------------------------------
 set ( SKIP_DOC_GEN FALSE CACHE BOOL
-  "Disable building the API documentation with ROBODoc" )
+  "Disable building the API documentation with FORD" )
 if ( NOT SKIP_DOC_GEN )
-  find_program ( ROBODOC robodoc )
-  if ( ROBODOC ) # Found
-    set ( ROBODOC_OPTIONS --rc ${CMAKE_SOURCE_DIR}/robodoc.rc
-      CACHE STRING "Options passed to robodoc to control building the documentation" )
-    set ( DOC_DIR "${CMAKE_BINARY_DIR}/documentation" )
-    set ( REQUIRED_ROBODOC_OPTIONS
-      --src "${CMAKE_SOURCE_DIR}/src" --doc "${DOC_DIR}"
-      --documenttitle "${CMAKE_PROJECT_NAME}" )
-    # Dynamically generate the ROBODoc outputs list
-    message ( STATUS "Dynamically computing ROBODoc output information..." )
-    execute_process ( COMMAND ${CMAKE_COMMAND} -E remove_directory ${DOC_DIR}
-      COMMAND ${CMAKE_COMMAND} -E make_directory ${DOC_DIR}
-      COMMAND "${ROBODOC}" ${REQUIRED_ROBODOC_OPTIONS} ${ROBODOC_OPTIONS} )
-    file ( GLOB_RECURSE ROBODOC_OUTPUTS
-      "${DOC_DIR}/*" )
-    execute_process ( COMMAND ${CMAKE_COMMAND} -E remove_directory ${DOC_DIR} )
-    message ( STATUS "Done dynamically computing ROBODoc outputs." )
+  find_program ( FORD ford )
+  if ( FORD ) # Found
+    file ( COPY "${CMAKE_SOURCE_DIR}/media" DESTINATION "${CMAKE_BINARY_DIR}/" )
+    set ( DOC_DIR "${CMAKE_BINARY_DIR}/doc" )
+    set ( FORD_PROJECT_FILE "${CMAKE_SOURCE_DIR}/json-fortran.md" )
+    # Dynamically generate the FORD outputs list
+    message ( STATUS "Dynamically computing FORD output information..." )
+    if ( NOT (DEFINED FORD_OUTPUTS_CACHED) )
+      message ( STATUS "Running FORD to dynamically compute documentation outputs, this could take a while..." )
+      execute_process ( COMMAND ${CMAKE_COMMAND} -E remove_directory ${DOC_DIR}
+	COMMAND ${CMAKE_COMMAND} -E make_directory ${DOC_DIR}
+	COMMAND "${FORD}" -d "${CMAKE_SOURCE_DIR}/src" -o "${DOC_DIR}" "${FORD_PROJECT_FILE}" OUTPUT_QUIET )
+    endif ()
+    file ( GLOB_RECURSE FORD_OUTPUTS
+      "${DOC_DIR}/*.html" )
+    file ( GLOB_RECURSE FORD_CLEAN_OUTPUTS
+      "${DOC_DIR}/*.*" )
+    if ( (DEFINED FORD_OUTPUTS) AND ( NOT ( "${FORD_OUTPUTS}" STREQUAL "" ) ) )
+      set ( FORD_OUTPUTS_CACHED "${FORD_OUTPUTS}"
+	CACHE INTERNAL "internal variable to attempt to prevent rebuilding FORD docs" FORCE )
+    endif ()
+    message ( STATUS "Done dynamically computing FORD outputs." )
 
     foreach ( SRC_FILE ${JF_LIB_SRCS} ${JF_TEST_SRCS} )
-      list ( APPEND ROBO_DEPENDS "${SRC_FILE}" )
+      list ( APPEND FORD_DEPENDS "${SRC_FILE}" )
     endforeach ( SRC_FILE )
-    add_custom_command ( OUTPUT ${ROBODOC_OUTPUTS}
-      COMMAND "${CMAKE_COMMAND}" -E make_directory "${DOC_DIR}" # Ensure DOC_DIR exists at build time
-      COMMAND "${ROBODOC}" ${REQUIRED_ROBODOC_OPTIONS} ${ROBODOC_OPTIONS}
-      DEPENDS ${ROBO_DEPENDS}
-      COMMENT "Building HTML documentation for ${CMAKE_PROJECT_NAME} using ROBODoc" )
+    add_custom_command ( OUTPUT ${FORD_OUTPUTS_CACHED}
+      COMMAND "${FORD}" -d "${CMAKE_SOURCE_DIR}/src" -o "${DOC_DIR}" "${FORD_PROJECT_FILE}"
+      MAIN_DEPENDENCY "${FORD_PROJECT_FILE}"
+      DEPENDS ${FORD_DEPENDS}
+      COMMENT "Building HTML documentation for ${CMAKE_PROJECT_NAME} using FORD" )
     add_custom_target ( documentation ALL
-      DEPENDS ${ROBODOC_OUTPUTS} )
+      DEPENDS ${FORD_OUTPUTS} )
     set ( INSTALL_API_DOCUMENTATION TRUE
-      CACHE BOOL "Install ROBODoc generated documentation?" )
+      CACHE BOOL "Install FORD generated documentation?" )
     if ( INSTALL_API_DOCUMENTATION )
       if ( USE_GNU_INSTALL_CONVENTION )
 	install ( DIRECTORY "${DOC_DIR}/" DESTINATION "${CMAKE_INSTALL_DOCDIR}" )
@@ -182,7 +187,7 @@ if ( NOT SKIP_DOC_GEN )
     endif ()
   else () # Not found
     message ( WARNING
-      "ROBODoc not found! Please set the CMake cache variable ROBODOC to point to the installed ROBODoc binary, and reconfigure or disable building the documentation. ROBODoc can be installed from: http://www.xs4all.nl/~rfsber/Robo/ If you do not wish to install ROBODoc and build the json-fortran documentation, then please set the CMake cache variable SKIP_DOC_GEN to TRUE." )
+      "FORD not found! Please set the CMake cache variable FORD to point to the installed FORD executable, and reconfigure or disable building the documentation. FORD can be installed from PYPI with `sudo pip install FORD` or from <https://github.com/cmacmackin/ford> If you do not wish to install FORD and build the json-fortran documentation, then please set the CMake cache variable SKIP_DOC_GEN to TRUE." )
   endif ()
 endif ()
 
@@ -209,7 +214,7 @@ if ( ENABLE_TESTS )
   set ( DATA_DIR "${CMAKE_BINARY_DIR}/files" )
 
   set_directory_properties ( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES
-    "${DATA_DIR}/test2.json;${DATA_DIR}/test4.json" )
+    "${DATA_DIR}/test2.json;${DATA_DIR}/test4.json;${FORD_CLEAN_OUTPUTS}" )
 
   # Validate input
   if ( JSONLINT )
@@ -222,7 +227,7 @@ if ( ENABLE_TESTS )
       get_filename_component ( TESTNAME "${VALID_JSON}" NAME )
       add_test ( NAME validate-${TESTNAME}
 	WORKING_DIRECTORY "${DATA_DIR}/inputs"
-	COMMAND ${JSONLINT} "${VALID_JSON}" )
+	COMMAND ${JSONLINT} "--allow=nonescape-characters" "${VALID_JSON}" )
     endforeach ()
 
     foreach ( INVALID ${INVALID_JSON} )
@@ -267,7 +272,7 @@ if ( ENABLE_TESTS )
       get_filename_component ( TESTNAME ${JSON_FILE} NAME )
       add_test ( NAME validate-output-${TESTNAME}
 	WORKING_DIRECTORY "${DATA_DIR}"
-	COMMAND ${JSONLINT} ${TESTNAME} )
+	COMMAND ${JSONLINT} "--allow=nonescape-characters" ${TESTNAME} )
       set_property ( TEST validate-output-${TESTNAME}
 	APPEND
 	PROPERTY

CONTRIBUTING.md

@@ -90,7 +90,7 @@ git rebase upstream/master
 - Please adhere to the code indentation and formatting as it currently exists, aligning common elements vertically, etc. Tab characters are not allowed. Indentations should be done with *4* space characters.
 - *Do NOT* allow your editor to make a bunch of indentation or white space changes, that will introduce non-substantive changes on lines that you have not actually edited.
 - The coding style is modern free-form Fortran, consistent with the Fortran 2008 standard.  Note that the two supported compilers (ifort and gfortran) do not currently include the entire Fortran 2008 standard. Therefore, only those language features supported by Gfortran 4.9 and Intel 13.1.0 are currently allowed.  This also means that previous versions of these compilers are not supported, and major changes to the code to support earlier compilers (or Fortran 95) will not be accepted.  At some point in the future (when compiler support has improved), all Fortran 2008 features will be allowed.
-- All subroutines and functions *must* be properly documented.  This includes useful inline comments as well as comment blocks using the [ROBODoc](http://rfsber.home.xs4all.nl/Robo/manual.html) syntax.
+- All subroutines and functions *must* be properly documented.  This includes useful inline comments as well as comment blocks using the [FORD](https://github.com/cmacmackin/ford/wiki/Writing-Documentation) syntax.
 - For simplicity, json-fortran currently consists of one module file. It is not envisioned that it will ever need to expand to include multiple files (if it does, there would need to be a very good reason).
 
 [top](#contributing-to-json-fortran)

README.md

@@ -68,7 +68,7 @@ brew install --with-unicode-support json-fortran
 _Please note_, if you wish to support usage of json-fortran with
 multiple Fortran compilers, please follow the CMake installation
 instructions below, as the homebrew installation is only intended to
-support a single Fortran compiler. Cheers! :beers:
+support a single Fortran compiler. Cheers!
 
 [top](#json-fortran)
 
@@ -287,7 +287,7 @@ The code above produces the file:
 Documentation
 --------------
 
-The API documentation for the latest release version can be found [here](http://jacobwilliams.github.io/json-fortran).  The documentation can also be generated by processing the source files with [RoboDoc](http://rfsber.home.xs4all.nl/Robo/).  Note that both the shell script, CMake, and SCons will also generate these files automatically in the documentation folder, assuming you have RoboDoc installed.
+The API documentation for the latest release version can be found [here](http://jacobwilliams.github.io/json-fortran).  The documentation can also be generated by processing the source files with [FORD](https://github.com/cmacmackin/ford).  Note that both the shell script, CMake, and SCons will also generate these files automatically in the documentation folder, assuming you have FORD installed.
 
 [top](#json-fortran)
 

build.sh

@@ -20,7 +20,7 @@
 #            profiling flags
 #        with :
 #            unit tests enabled
-#            documentation (if ROBODoc is installed)
+#            documentation (if FORD is installed)
 #
 #     More recent (right-most) flags will override preceding flags
 #     flags:
@@ -51,19 +51,19 @@
 #                                 fortran unit tests
 #
 #        --skip-documentation [{yes|no}]: Skip (or don't skip) building the json-
-#                                         fortran documentation using ROBODoc
+#                                         fortran documentation using FORD
 #
 #  REQUIRES
 #    FoBiS.py : https://github.com/szaghi/FoBiS      [version 1.2.5 or later required]
-#    RoboDoc  : http://rfsber.home.xs4all.nl/Robo/   [version 4.99.38 is the one tested]
+#    FORD     : https://github.com/cmacmackin/ford   [version 3.0.2 is the one tested]
 #
 #  AUTHOR
 #    Jacob Williams : 12/27/2014
 #
 
 set -e
 
-PROJECTNAME='jsonfortran'       # project name for robodoc (example: jsonfortran_2.0.0)
+FORDMD='json-fortran.md'        # FORD options file for building documentation
 DOCDIR='./documentation/'       # build directory for documentation
 SRCDIR='./src/'                 # library source directory
 TESTDIR='./src/tests/'          # unit test source directory
@@ -280,14 +280,14 @@ else
     echo "Skip building the unit tests since \$JF_SKIP_TESTS has been set to 'true'."
 fi
 
-#build the documentation with RoboDoc (if present):
+#build the documentation with ford (if present):
 echo ""
 if [[ $JF_SKIP_DOCS != [yY]* ]]; then
-    if hash robodoc 2>/dev/null; then
+    if hash ford 2>/dev/null; then
 	echo "Building documentation..."
-	robodoc --rc ./robodoc.rc --src ${SRCDIR} --doc ${DOCDIR} --documenttitle ${PROJECTNAME}
+	ford $FORDMD
     else
-	echo "ROBODoc not found! Cannot build documentation. ROBODoc can be installed from: http://www.xs4all.nl/~rfsber/Robo/"
+	echo "FORD not found! Install using: sudo pip install ford"
     fi
 else
     echo "Skip building documentation since \$JF_SKIP_DOCS has been set to ${JF_SKIP_DOCS}."

json-fortran.md

@@ -0,0 +1,46 @@
+project: json-fortran
+favicon: ./media/json-fortran-32x32.png
+project_dir: ./src
+macro: USE_UCS4
+output_dir: ./doc
+media_dir: ./media
+project_github: https://github.com/jacobwilliams/json-fortran
+summary: JSON-FORTRAN -- A Fortran 2008 JSON API
+author: Jacob Williams
+github: https://github.com/jacobwilliams
+website: http://degenerateconic.com
+twitter: https://twitter.com/degenerateconic
+predocmark_alt: >
+predocmark: <
+docmark_alt:
+docmark: !
+exclude_dir: tests
+exclude_dir: introspection
+display: public
+         protected
+         private
+source: true
+md_extensions: markdown.extensions.toc(anchorlink=True)
+               markdown.extensions.smarty(smart_quotes=False)
+
+<!-- Uncommenting these should work, but this actually causes issues
+
+*[API]: Application Programmable Interface
+*[JSON]: JavaScript Object Notation
+
+-->
+
+[TOC]
+
+# Brief description
+
+A user-friendly and object-oriented API for reading and writing JSON files, written in
+modern Fortran (Fortran 2003+).  The source code is a single Fortran module file ([json_module.F90](https://github.com/jacobwilliams/json-fortran/blob/master/src/json_module.F90)).
+
+# License
+
+The json-fortran source code and related files and documentation are distributed under a permissive free software license (BSD-style).  See the [LICENSE](https://raw.githubusercontent.com/jacobwilliams/json-fortran/master/LICENSE) file for more details.
+
+# Miscellaneous
+
+* For more information about JSON, see: <http://www.json.org/>