Merge remote-tracking branch 'trondeau-github/sphinxdocs' into sphinxdocs

14 files changed, 200 insertions, 146 deletions

diff --git a/cmake/Modules/FindSphinx.cmake b/cmake/Modules/FindSphinx.cmake
new file mode 100644
index 000000000..da12ee93d
--- /dev/null
+++ b/cmake/Modules/FindSphinx.cmake
@@ -0,0 +1,37 @@
+# - This module looks for Sphinx
+# Find the Sphinx documentation generator
+#
+# This modules defines
+#  SPHINX_EXECUTABLE
+#  SPHINX_FOUND
+
+#=============================================================================
+# Copyright 2002-2009 Kitware, Inc.
+# Copyright 2009-2011 Peter Colberg
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
+#
+# This software is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the License for more information.
+#=============================================================================
+# (To distribute this file outside of CMake, substitute the full
+#  License text for the above reference.)
+
+find_program(SPHINX_EXECUTABLE NAMES sphinx-build
+  HINTS
+  $ENV{SPHINX_DIR}
+  PATH_SUFFIXES bin
+  DOC "Sphinx documentation generator"
+)
+
+include(FindPackageHandleStandardArgs)
+
+find_package_handle_standard_args(Sphinx DEFAULT_MSG
+  SPHINX_EXECUTABLE
+)
+
+mark_as_advanced(
+  SPHINX_EXECUTABLE
+)
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index f67fdd7a8..24bf2405e 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -21,12 +21,14 @@
 # Setup dependencies
 ########################################################################
 find_package(Doxygen)
+find_package(Sphinx)
 
 ########################################################################
 # Register component
 ########################################################################
 include(GrComponent)
 GR_REGISTER_COMPONENT("doxygen" ENABLE_DOXYGEN DOXYGEN_FOUND)
+GR_REGISTER_COMPONENT("sphinx"  ENABLE_SPHINX  SPHINX_FOUND)
 
 ########################################################################
 # Begin conditional configuration
@@ -48,3 +50,25 @@ CPACK_COMPONENT("docs"
 add_subdirectory(doxygen)
 
 endif(ENABLE_DOXYGEN)
+
+
+########################################################################
+# Begin conditional configuration
+########################################################################
+if(ENABLE_SPHINX)
+
+########################################################################
+# Setup CPack components
+########################################################################
+include(GrPackage)
+CPACK_COMPONENT("docs"
+    DISPLAY_NAME "Documentation"
+    DESCRIPTION  "Sphinx generated documentation"
+)
+
+########################################################################
+# Add subdirectories
+########################################################################
+add_subdirectory(sphinx)
+
+endif(ENABLE_SPHINX)
diff --git a/docs/doxygen/Doxyfile.in b/docs/doxygen/Doxyfile.in
index f3485316c..ad3c2d01f 100644
--- a/docs/doxygen/Doxyfile.in
+++ b/docs/doxygen/Doxyfile.in
@@ -628,7 +628,6 @@ EXCLUDE                = @abs_top_builddir@/docs/doxygen/html \
                          @abs_top_builddir@/gr-gsm-fr-vocoder/src/lib/gsm_full_rate.py \
                          @abs_top_builddir@/gr-gsm-fr-vocoder/src/python/encdec.py \
                          @abs_top_builddir@/gr-howto-write-a-block \
-                         @abs_top_builddir@/gr-howto-write-a-block-cmake \
                          @abs_top_builddir@/gr-pager/src/pager_swig.py \
                          @abs_top_builddir@/gr-trellis/doc \
                          @abs_top_builddir@/gr-trellis/src/lib/generate_all.py \
@@ -640,7 +639,7 @@ EXCLUDE                = @abs_top_builddir@/docs/doxygen/html \
 			 @abs_top_builddir@/_CPack_Packages \
                          @abs_top_srcdir@/cmake \
 			 @abs_top_srcdir@/gr-qtgui/lib \
-                         @abs_top_srcdir@/gr-howto-write-a-block-cmake
+                         @abs_top_srcdir@/gr-howto-write-a-block
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or
 # directories that are symbolic links (a Unix filesystem feature) are excluded
diff --git a/docs/sphinx/CMakeLists.txt b/docs/sphinx/CMakeLists.txt
new file mode 100644
index 000000000..38d77fb3a
--- /dev/null
+++ b/docs/sphinx/CMakeLists.txt
@@ -0,0 +1,35 @@
+# Copyright 2012 Free Software Foundation, Inc.
+# 
+# This file is part of GNU Radio
+# 
+# GNU Radio is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+# 
+# GNU Radio is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with GNU Radio; see the file COPYING.  If not, write to
+# the Free Software Foundation, Inc., 51 Franklin Street,
+# Boston, MA 02110-1301, USA.
+
+include(GrPython)
+
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/source/conf.py.in
+    ${CMAKE_CURRENT_BINARY_DIR}/conf.py
+@ONLY)
+
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/run_sphinx_build.sh.in
+    ${CMAKE_BINARY_DIR}/run_sphinx_build.sh
+@ONLY)
+
+if(UNIX)
+  #make the shell file executable
+  execute_process(COMMAND chmod +x ${CMAKE_BINARY_DIR}/run_sphinx_build.sh)
+endif(UNIX)
diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile
deleted file mode 100644
index 3fcbff238..000000000
--- a/docs/sphinx/Makefile
+++ /dev/null
@@ -1,130 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = build
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
-
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	-rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/GNURadio.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/GNURadio.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/GNURadio"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/GNURadio"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	make -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
diff --git a/docs/sphinx/README b/docs/sphinx/README
new file mode 100644
index 000000000..31fd47fe2
--- /dev/null
+++ b/docs/sphinx/README
@@ -0,0 +1,38 @@
+INTRODUCTION
+The Sphinx documentation system uses the fully installed Python tree
+to build a set of documents (generally in HTML). In GNU Radio, the
+documentation system is done through Doxygen in the public header
+(/include/foo.h) files. Doxygen first builds its documentation files,
+then the swig_docs program uses Doxygen's XML output and smashed the
+documentation from each header file into the SWIG'd Python
+block. Basically, using a single documentation markup, Doxygen, we
+expose the documentation strings in both the Doxygen-built manual and
+within the Python blocks themselves.
+
+Sphinx takes this process one step farther by reading the docstrings
+of all Python blocks and creating its own manual. This has two
+benefits. First, the Sphinx documentation looks nice and is formatted
+in such a way that Python users of GNU Radio can easy see the module
+structure and hierarchy. It also allows not only takes the Doxygen
+documentation from C++, but it also allows us to take any Python files
+and include their documentation. 
+
+The end result is two manuals: one for Python and one for C++ users
+without having to duplicate comments, markup, or documentation.
+
+
+BUILDING THE SPHINX MANUAL
+Building the Sphinx docs takes some manual intervention as it
+requires GNU Radio to already be installed. So first follow the steps
+to build and install GNU Radio.
+
+In the build directory, a helper file is created called
+run_sphinx_build.sh. This is a Linux shell script that runs the
+sphinx-build command with all of the normal settings and important
+directories preloaded. For non Linux systems, it should be easy to
+pull out the executable and options to run it by hand.
+
+The run_sphinx_build.sh outputs the manual into
+$builddir/docs/sphinx/sphinx_out. Open up the index.html file in a
+browser to view it.
+
diff --git a/docs/sphinx/run_sphinx_build.sh.in b/docs/sphinx/run_sphinx_build.sh.in
new file mode 100644
index 000000000..bc89f2de7
--- /dev/null
+++ b/docs/sphinx/run_sphinx_build.sh.in
@@ -0,0 +1,7 @@
+#!/bin/bash
+
+echo "Creating Sphinx documentation in: @CMAKE_CURRENT_BINARY_DIR@/sphinx_out"
+
+LD_LIBRARY_PATH="@CMAKE_INSTALL_PREFIX@/lib"
+@SPHINX_EXECUTABLE@ -b html -c @CMAKE_CURRENT_BINARY_DIR@/ @CMAKE_CURRENT_SOURCE_DIR@/source @CMAKE_CURRENT_BINARY_DIR@/sphinx_out
+
diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py.in
index 6fa24218e..37b945aa7 100644
--- a/docs/sphinx/source/conf.py
+++ b/docs/sphinx/source/conf.py.in
@@ -16,7 +16,8 @@ import sys, os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath('@CMAKE_CURRENT_SOURCE_DIR@'))
+sys.path.insert(0, '@CMAKE_INSTALL_PREFIX@/@GR_PYTHON_DIR@')
 
 # -- General configuration -----------------------------------------------------
 
diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst
index d931a0dcb..887271ce0 100644
--- a/docs/sphinx/source/index.rst
+++ b/docs/sphinx/source/index.rst
@@ -73,3 +73,46 @@ Framework Extensions
    gnuradio.pager <pager/index>
    gnuradio.video_sdl <video_sdl>
    gnuradio.vocoder <vocoder/index>
+
+
+.. Use this to add to the toctree but not displayed
+.. It's mostly to get rid of warnings
+ 
+.. toctree::
+   :hidden:   
+   
+   coding <gr/coding_blk>
+   converter <gr/converter_blk>
+   demodulation <gr/demodulation_blk>
+   dft <gr/dft_blk>
+   filter <gr/filter_blk>
+   filter_design <gr/filter_design>
+   internal <gr/internal>
+   level <gr/level_blk>
+   math <gr/math_blk>
+   misc <gr/misc>
+   misc <gr/misc_blk>
+   modulation <gr/modulation_blk>
+   sink <gr/sink_blk>
+   slicedice <gr/slicedice_blk>
+   source <gr/source_blk>
+   sync <gr/sync_blk>
+   top_block <gr/top_block>
+
+   atsc_blks <atsc/blks>
+   blks <blks2/blks>
+   blks2_utilities <blks2/utilities>
+   digital_blocks <digital/blocks>
+   constellations <digital/constellations>
+   ofdm <digital/ofdm>
+   pkt_utils <digital/pkt_utils>
+   digital_utilities <digital/utilities>
+   optfir <optfir/detail>
+   pager_blks <pager/blks>
+   pyqt_filter <pyqt_filter>
+   pyqt_plot <pyqt_plot>
+   trellis_blks <trellis/blks>
+   trellis_objs <trellis/objs>
+   vocoder_blks <vocoder/blks>
+   window_detail <window/detail>
+   wxgui_blks <wxgui/blks>
diff --git a/gr-digital/include/digital_cma_equalizer_cc.h b/gr-digital/include/digital_cma_equalizer_cc.h
index 0d703789a..79e84ca4b 100644
--- a/gr-digital/include/digital_cma_equalizer_cc.h
+++ b/gr-digital/include/digital_cma_equalizer_cc.h
@@ -41,9 +41,9 @@ digital_make_cma_equalizer_cc(int num_taps, float modulus, float mu, int sps);
  *
  * The error value and tap update equations (for p=2) can be found in:
  *
- * D. Godard, "Self-Recovering Equalization and Carrier Tracking in
+ * "D. Godard, "Self-Recovering Equalization and Carrier Tracking in
  * Two-Dimensional Data Communication Systems," IEEE Transactions on
- * Communications, Vol. 28, No. 11, pp. 1867 - 1875, 1980,
+ * Communications, Vol. 28, No. 11, pp. 1867 - 1875, 1980."
  */
 class DIGITAL_API digital_cma_equalizer_cc : public gr_adaptive_fir_ccc
 {
diff --git a/gr-digital/include/digital_constellation_receiver_cb.h b/gr-digital/include/digital_constellation_receiver_cb.h
index 8547bdd68..3a14bb5de 100644
--- a/gr-digital/include/digital_constellation_receiver_cb.h
+++ b/gr-digital/include/digital_constellation_receiver_cb.h
@@ -60,9 +60,9 @@ digital_make_constellation_receiver_cb (digital_constellation_sptr constellation
  * The symbol synchronization is done using a modified Mueller and
  * Muller circuit from the paper:
  * 
- *    G. R. Danesfahani, T.G. Jeans, "Optimisation of modified Mueller
- *    and Muller algorithm," Electronics Letters, Vol. 31, no. 13, 22
- *    June 1995, pp. 1032 - 1033.
+ * "G. R. Danesfahani, T.G. Jeans, "Optimisation of modified Mueller
+ * and Muller algorithm," Electronics Letters, Vol. 31, no. 13, 22
+ * June 1995, pp. 1032 - 1033."
  *
  * This circuit interpolates the downconverted sample (using the NCO
  * developed by the Costas loop) every mu samples, then it finds the
diff --git a/gr-digital/include/digital_fll_band_edge_cc.h b/gr-digital/include/digital_fll_band_edge_cc.h
index f07d7ba42..c70bfc86d 100644
--- a/gr-digital/include/digital_fll_band_edge_cc.h
+++ b/gr-digital/include/digital_fll_band_edge_cc.h
@@ -65,8 +65,8 @@ DIGITAL_API digital_fll_band_edge_cc_sptr digital_make_fll_band_edge_cc (float s
  * abs(x_l(t))^2 - abs(x_u(t))^2 = norm(x_l(t)) - norm(x_u(t)).
  *
  * In theory, the band-edge filter is the derivative of the matched
- * filter in frequency, (H_be(f) = \\frac{H(f)}{df}. In practice, this
- * comes down to a quarter sine wave at the point of the matched
+ * filter in frequency, (H_be(f) = frac{H(f)}{df}). In practice,
+ * this comes down to a quarter sine wave at the point of the matched
  * filter's rolloff (if it's a raised-cosine, the derivative of a
  * cosine is a sine).  Extend this sine by another quarter wave to
  * make a half wave around the band-edges is equivalent in time to the
diff --git a/gr-digital/include/digital_kurtotic_equalizer_cc.h b/gr-digital/include/digital_kurtotic_equalizer_cc.h
index 3ac8712d5..fed88c374 100644
--- a/gr-digital/include/digital_kurtotic_equalizer_cc.h
+++ b/gr-digital/include/digital_kurtotic_equalizer_cc.h
@@ -39,9 +39,9 @@ digital_make_kurtotic_equalizer_cc(int num_taps, float mu);
  * \ingroup eq_blk
  * \ingroup digital
  *
- * Y. Guo, J. Zhao, Y. Sun, "Sign kurtosis maximization based blind
+ * "Y. Guo, J. Zhao, Y. Sun, "Sign kurtosis maximization based blind
  * equalization algorithm," IEEE Conf. on Control, Automation,
- * Robotics and Vision, Vol. 3, Dec. 2004, pp. 2052 - 2057.
+ * Robotics and Vision, Vol. 3, Dec. 2004, pp. 2052 - 2057."
  */
 class DIGITAL_API digital_kurtotic_equalizer_cc : public gr_adaptive_fir_ccc
 {
diff --git a/gr-digital/include/digital_mpsk_receiver_cc.h b/gr-digital/include/digital_mpsk_receiver_cc.h
index 02cea8d25..1f11a26b6 100644
--- a/gr-digital/include/digital_mpsk_receiver_cc.h
+++ b/gr-digital/include/digital_mpsk_receiver_cc.h
@@ -65,10 +65,10 @@ digital_make_mpsk_receiver_cc (unsigned int M, float theta,
  *
  * The symbol synchronization is done using a modified Mueller and
  * Muller circuit from the paper:
- * 
- *    G. R. Danesfahani, T.G. Jeans, "Optimisation of modified Mueller
- *    and Muller algorithm," Electronics Letters, Vol. 31, no. 13, 22
- *    June 1995, pp. 1032 - 1033.
+ *
+ * "G. R. Danesfahani, T. G. Jeans, "Optimisation of modified Mueller
+ * and Muller algorithm," Electronics Letters, Vol. 31, no. 13, 22
+ * June 1995, pp. 1032 - 1033."
  *
  * This circuit interpolates the downconverted sample (using the NCO
  * developed by the Costas loop) every mu samples, then it finds the