reorganize docs using Sphinx

doc/CMakeLists.txt

@@ -1,40 +1,24 @@
 include(../cmakemodules/AssureCMakeRootFile.cmake) # Avoid user mistake in CMake source directory
 
+project(documentation)
 
 # Dummy documentation target for showing grouped files in IDEs:
 # ----------------------------------------------------------------------------
-file(GLOB DOX_HDRS "${CMAKE_SOURCE_DIR}/doc/doxygen-pages/*.h")
 file(GLOB_RECURSE RST_FILES "${CMAKE_SOURCE_DIR}/doc/*.rst")
+file(GLOB_RECURSE H_FILES "${CMAKE_SOURCE_DIR}/doc/sources/*.h")
 set(DOC_INDIV_FILES
 	"${CMAKE_SOURCE_DIR}/README.md"
 	)
-set(all_docs_files ${DOX_HDRS} ${RST_FILES} ${DOC_INDIV_FILES})
+set(all_docs_files ${RST_FILES} ${H_FILES} ${DOC_INDIV_FILES})
 add_custom_target(DocumentationFiles DEPENDS ${all_docs_files} SOURCES ${all_docs_files})
 set_target_properties(DocumentationFiles PROPERTIES FOLDER "documentation")
 
+# Manpages
 # ----------------------------------------------------------------------------
-# Targets for building the documentation of the MRPT
-# ----------------------------------------------------------------------------
-
-project(documentation)
-
 if(UNIX)
 	add_subdirectory(man-pages)
 endif()
 
-if(DOXYGEN_EXECUTABLE)
-	# --------------------------------
-	#   documentation_html
-	# --------------------------------
-	add_custom_target(documentation_html
-		COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/build.py ${MRPT_VERSION}
-		COMMENT "Generating MRPT documentation (html)"
-		SOURCES build.py conf.py _templates/layout.html ${RST_FILES}
-		)
-	set_target_properties(documentation_html PROPERTIES FOLDER "documentation")
-endif()
-
-
 # Compile Latex targets:
 if(NOT WIN32)
 find_program(LATEXMK_PROGRAM latexmk)
@@ -49,6 +33,5 @@ if(LATEXMK_PROGRAM)
 		COMMENT 		"Generating graphslam-engine-guide (ps.gz)"
 		)
 	add_dependencies(documentation_psgz_guides documentation_graphslam-engine-guide)
-
 endif()
 endif()

doc/Makefile

@@ -0,0 +1,50 @@
+
+.DEFAULT_GOAL := all
+
+# Replace this path with your local build of doxyrest:
+export PYTHONPATH := $(HOME)/code/doxyrest_b/doxyrest/sphinx/:$(PYTHONPATH)
+export PATH := $(HOME)/code/doxyrest_b/build/doxyrest/bin/Release:$(PATH)
+export MRPT_VERSION_STR := $(shell head -n1 ../version_prefix.txt)
+export MRPT_LIST_INCLUDE_DIRS := $(shell for f in ../libs/*/include; do printf "$$(realpath $$f) "; done)
+export MRPT_DOX_INPUT_DIRS := $(shell for f in ../libs/*; do printf "$$(realpath $$f) "; done)
+
+# Use to quickly test the documentation scripts:
+ifeq ($(MRPT_DOCS_FAST_TEST),1)
+export MRPT_DOX_INPUT_DIRS := $(shell realpath ../libs/core)
+endif
+
+
+.PHONY: clean
+clean:
+	rm -fr html
+	rm -fr \
+		source/xml-dir \
+		source/class_* \
+		source/enum_* \
+		source/namespace_* \
+		source/group_* \
+		source/struct_* \
+		source/page_* \
+		source/union_* \
+		source/global.rst source/doxygen-index.rst \
+		2> /dev/null || true
+
+.PHONY: all
+all:
+	make html
+
+html-and-view:
+	make html
+	xdg-open html/index.html
+
+html:
+	echo "Building docs for these directories: ${MRPT_DOX_INPUT_DIRS}"
+	echo "Using MRPT_LIST_INCLUDE_DIRS: ${MRPT_LIST_INCLUDE_DIRS}"
+	# 1) Build Doxygen
+	cd source && doxygen
+	# 2) Doxygen XML -> RST
+	cd source && doxyrest -c doxyrest-config.lua
+	# Remove main doc file created for nanoflann:
+	rm source/page_index.rst 2>/dev/null || true
+	# 3) RST -> HTML with Sphinx
+	sphinx-build -b html source/ html/

doc/README.md

@@ -0,0 +1,22 @@
+Root directory for MRPT Sphinx documentation.
+
+# Requisites
+
+```
+# Install Sphinx & dependencies:
+sudo -H pip install sphinx_rtd_theme
+```
+
+Install doxyrest: [instructions](https://github.com/vovkos/doxyrest_b/blob/master/README.rst).
+
+
+# How to generate docs
+
+From the MRPT source tree:
+
+```
+cd docs
+make
+```
+
+You may need to either modify PATH and PYTHONPATH in your env, or edit the hard-coded paths in mrpt/docs/Makefile