Merge pull request #2248 from afh/improve-web-docs

Improve web docs

3 files changed, 43 insertions, 17 deletions

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 61e5c077..ef93c293 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -89,6 +89,7 @@ if (BUILD_DOCS)
   find_program(TEXI2PDF texi2pdf)
   find_program(TEX tex)
   find_program(MAN2HTML man2html)
+  find_program(MANDOC mandoc)
   find_program(GROFF groff)
   set(ledger_info_files ledger3.texi)
 
@@ -108,18 +109,22 @@ foreach(file ${ledger_info_files})
 
   if (MAKEINFO)
     add_custom_command(OUTPUT ${file_base}.info
-      COMMAND makeinfo --force --no-split -o ${file_base}.info ${CMAKE_CURRENT_SOURCE_DIR}/${file}
+      COMMAND ${MAKEINFO} --force --no-split -o ${file_base}.info ${CMAKE_CURRENT_SOURCE_DIR}/${file}
       DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${file}
       VERBATIM)
     list(APPEND ledger_doc_files ${file_base}.info)
-  endif()
-
-  if (BUILD_WEB_DOCS AND MAKEINFO)
-    add_custom_command(OUTPUT ${file_base}.html
-      COMMAND makeinfo --force --html --no-split -o ${file_base}.html ${CMAKE_CURRENT_SOURCE_DIR}/${file}
-      DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${file}
-      VERBATIM)
-    list(APPEND ledger_doc_files ${file_base}.html)
+    if (BUILD_WEB_DOCS)
+      add_custom_command(OUTPUT ${file_base}.html
+        COMMAND ${MAKEINFO} --force --html --no-split -o ${file_base}.html ${CMAKE_CURRENT_SOURCE_DIR}/${file}
+        DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${file}
+        VERBATIM)
+      list(APPEND ledger_doc_files ${file_base}.html)
+      add_custom_command(OUTPUT ${file_base}.txt
+        COMMAND ${MAKEINFO} --force --plaintext --no-split -o ${file_base}.txt ${CMAKE_CURRENT_SOURCE_DIR}/${file}
+        DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${file}
+        VERBATIM)
+      list(APPEND ledger_doc_files ${file_base}.txt)
+    endif()
   endif()
 
   if (TEXI2PDF AND TEX)
@@ -127,7 +132,7 @@ foreach(file ${ledger_info_files})
       set(papersize --texinfo=@afourpaper)
     endif()
     add_custom_command(OUTPUT ${file_base}.pdf
-      COMMAND texi2pdf ${papersize} -b -q -o ${file_base}.pdf ${CMAKE_CURRENT_SOURCE_DIR}/${file}
+      COMMAND ${TEXI2PDF} ${papersize} -b -q -o ${file_base}.pdf ${CMAKE_CURRENT_SOURCE_DIR}/${file}
       DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${file}
       VERBATIM)
     list(APPEND ledger_doc_files ${file_base}.pdf)
@@ -143,18 +148,39 @@ if (BUILD_WEB_DOCS)
   endif()
   if (MAN2HTML)
     add_custom_command(OUTPUT ledger.1.html
-      COMMAND ${BASH} -c "man2html ${CMAKE_CURRENT_SOURCE_DIR}/ledger.1 | tail -n+3 > ledger.1.html"
+      COMMAND ${BASH} -c "${MAN2HTML} ${CMAKE_CURRENT_SOURCE_DIR}/ledger.1 | tail -n+3 > ledger.1.html"
       DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/ledger.1
       VERBATIM)
     list(APPEND ledger_doc_files ledger.1.html)
-  elseif(GROFF)
+  elseif (MANDOC OR GROFF)
+    set(_cmd ${MANDOC})
+    if (NOT _cmd)
+      # HTML produced by mandoc is much nicer looking, use groff only as a last resort.
+      message(WARNING "Using ${GROFF} to generate ledger1.html, as mandoc could not be found.")
+      set(_cmd ${GROFF})
+    endif()
     add_custom_command(OUTPUT ledger.1.html
-      COMMAND ${BASH} -c "groff -mandoc -Thtml ${CMAKE_CURRENT_SOURCE_DIR}/ledger.1 > ledger.1.html"
+      COMMAND ${BASH} -c "${_cmd} -mandoc -Thtml ${CMAKE_CURRENT_SOURCE_DIR}/ledger.1 > ledger.1.html"
       DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/ledger.1
       VERBATIM)
     list(APPEND ledger_doc_files ledger.1.html)
+    add_custom_command(OUTPUT ledger.1.pdf
+      COMMAND ${BASH} -c "${_cmd} -mandoc -Tpdf ${CMAKE_CURRENT_SOURCE_DIR}/ledger.1 > ledger.1.pdf"
+      DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/ledger.1
+      VERBATIM)
+    list(APPEND ledger_doc_files ledger.1.pdf)
   else()
-    message(FATAL_ERROR "Could not find man2html or groff. HTML version of man page cannot be built.")
+    message(WARNING "Could not find man2html or groff. HTML version of man page will not be built.")
+  endif()
+
+  if (USE_PYTHON AND Python_EXECUTABLE)
+    add_custom_command(OUTPUT ledger.html
+      COMMAND ${CMAKE_COMMAND} -E env
+        PYTHONPATH=${CMAKE_BINARY_DIR}
+        ${Python_EXECUTABLE} -m pydoc -w ledger
+      DEPENDS ${CMAKE_BINARY_DIR}/${_ledger_python_module_name}
+      VERBATIM)
+    list(APPEND ledger_doc_files ledger.html)
   endif()
 endif(BUILD_WEB_DOCS)
 
diff --git a/doc/ledger.1 b/doc/ledger.1
index fab5625a..82b03b46 100644
--- a/doc/ledger.1
+++ b/doc/ledger.1
@@ -1449,7 +1449,7 @@ initializations.
 .Sh SEE ALSO
 .Xr beancount 1 ,
 .Xr hledger 1
-
+.Pp
 The full documentation for
 .Nm
 is maintained as a Texinfo manual.  If the
diff --git a/doc/mainpage.txt b/doc/mainpage.txt
index 95db4d12..7958559d 100644
--- a/doc/mainpage.txt
+++ b/doc/mainpage.txt
@@ -1,9 +1,9 @@
 /**
-\mainpage API Documentation
+\mainpage C++ API Documentation
 
 \section intro_sec Introduction
 
-Documentation of the Ledger API is an ongoing process and you are invited
+Documentation of the Ledger C++ API is an ongoing process and you are invited
 to help out and contribute. In case you find this documentation incorrect,
 incomplete, unclear, or lacking please
 [open a pull request](https://git.ledger-cli.org/ledger/pulls).