From 8ee7c96ff6ffd8829a0dd29e4a4745eeaeee780f Mon Sep 17 00:00:00 2001 From: Tom Rondeau Date: Tue, 1 May 2012 11:18:31 -0400 Subject: docs: adds a 'make sphinx' target that can be run after 'make install' to generate the Python docs. --- cmake/Modules/FindSphinx.cmake | 37 ++++++++++++++++++++++++++++++++++++ docs/CMakeLists.txt | 24 +++++++++++++++++++++++ docs/sphinx/CMakeLists.txt | 43 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 104 insertions(+) create mode 100644 cmake/Modules/FindSphinx.cmake create mode 100644 docs/sphinx/CMakeLists.txt 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/sphinx/CMakeLists.txt b/docs/sphinx/CMakeLists.txt new file mode 100644 index 000000000..fcae4eb31 --- /dev/null +++ b/docs/sphinx/CMakeLists.txt @@ -0,0 +1,43 @@ +# 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) + +# You can set these variables from the command line. +set(SPHINXOPTS) +set(SPHINXBUILD sphinx-build) +set(PAPER) +set(BUILDDIR ${CMAKE_CURRENT_BINARY_DIR}/build) +set(SRCDIR ${CMAKE_CURRENT_SOURCE_DIR}/source) + +# Internal variables. +set(PAPEROPT_a4 -D latex_paper_size=a4) +set(PAPEROPT_letter -D latex_paper_size=letter) +set(ALLSPHINXOPTS -d ${BUILDDIR}/doctrees ${PAPEROPT_${PAPER}} ${SPHINXOPTS} ${SRCDIR}) + +# Set up environmental variables to pass to sphinx +set(LDPATH LD_LIBRARY_PATH=${CMAKE_INSTALL_PREFIX}/${GR_LIBRARY_DIR}) +set(PYPATH PYTHONPATH=${CMAKE_INSTALL_PREFIX}/${GR_PYTHON_DIR}) +message(STATUS "ENVIRONS: ${LDPATH} ${PYPATH}") + +add_custom_target(sphinx + COMMAND ${LDPATH} ${PYPATH} ${SPHINX_EXECUTABLE} -b html ${ALLSPHINXOPTS} ${BUILDDIR}/html + COMMENT "Building Sphinx Documents from installed system." + ) + -- cgit From da42490eb23389949473c445b9cfb2a6f109440f Mon Sep 17 00:00:00 2001 From: Tom Rondeau Date: Tue, 1 May 2012 15:37:12 -0400 Subject: docs: fixed bug in doxygen looking at howto dir. --- docs/doxygen/Doxyfile.in | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 -- cgit From 59165ed2ec7d45a7875c003ce4ce713082cf62c8 Mon Sep 17 00:00:00 2001 From: Tom Rondeau Date: Tue, 1 May 2012 15:37:33 -0400 Subject: sphinx: create a conf.py and run_sphinx_build.sh files. These files help a user run Sphinx on the installed system. The shell script is designed for ease of use. --- docs/sphinx/CMakeLists.txt | 32 ++---- docs/sphinx/Makefile | 130 ---------------------- docs/sphinx/run_sphinx_build.sh.in | 7 ++ docs/sphinx/source/conf.py | 216 ------------------------------------ docs/sphinx/source/conf.py.in | 217 +++++++++++++++++++++++++++++++++++++ 5 files changed, 236 insertions(+), 366 deletions(-) delete mode 100644 docs/sphinx/Makefile create mode 100644 docs/sphinx/run_sphinx_build.sh.in delete mode 100644 docs/sphinx/source/conf.py create mode 100644 docs/sphinx/source/conf.py.in diff --git a/docs/sphinx/CMakeLists.txt b/docs/sphinx/CMakeLists.txt index fcae4eb31..38d77fb3a 100644 --- a/docs/sphinx/CMakeLists.txt +++ b/docs/sphinx/CMakeLists.txt @@ -19,25 +19,17 @@ include(GrPython) -# You can set these variables from the command line. -set(SPHINXOPTS) -set(SPHINXBUILD sphinx-build) -set(PAPER) -set(BUILDDIR ${CMAKE_CURRENT_BINARY_DIR}/build) -set(SRCDIR ${CMAKE_CURRENT_SOURCE_DIR}/source) +configure_file( + ${CMAKE_CURRENT_SOURCE_DIR}/source/conf.py.in + ${CMAKE_CURRENT_BINARY_DIR}/conf.py +@ONLY) -# Internal variables. -set(PAPEROPT_a4 -D latex_paper_size=a4) -set(PAPEROPT_letter -D latex_paper_size=letter) -set(ALLSPHINXOPTS -d ${BUILDDIR}/doctrees ${PAPEROPT_${PAPER}} ${SPHINXOPTS} ${SRCDIR}) - -# Set up environmental variables to pass to sphinx -set(LDPATH LD_LIBRARY_PATH=${CMAKE_INSTALL_PREFIX}/${GR_LIBRARY_DIR}) -set(PYPATH PYTHONPATH=${CMAKE_INSTALL_PREFIX}/${GR_PYTHON_DIR}) -message(STATUS "ENVIRONS: ${LDPATH} ${PYPATH}") - -add_custom_target(sphinx - COMMAND ${LDPATH} ${PYPATH} ${SPHINX_EXECUTABLE} -b html ${ALLSPHINXOPTS} ${BUILDDIR}/html - COMMENT "Building Sphinx Documents from installed system." - ) +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 ' where 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/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 deleted file mode 100644 index f5422ee41..000000000 --- a/docs/sphinx/source/conf.py +++ /dev/null @@ -1,216 +0,0 @@ -# -*- coding: utf-8 -*- -# -# GNU Radio documentation build configuration file, created by -# sphinx-quickstart on Sun Oct 16 22:27:51 2011. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -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('..')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.autosummary', 'gnuradio_sphinx', 'hieroglyph'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'GNU Radio (Unofficial Documentation)' -copyright = u'2011, Gnu Radio Developers' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = 'blah.blah' -# The full version, including alpha/beta/rc tags. -release = 'blah.blah.blah' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = [] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'default' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'GNURadiodoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'GNURadio.tex', u'GNU Radio Documentation', - u'Gnu Radio Developers', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'gnuradio', u'GNU Radio Documentation', - [u'Gnu Radio Developers'], 1) -] diff --git a/docs/sphinx/source/conf.py.in b/docs/sphinx/source/conf.py.in new file mode 100644 index 000000000..23a923a00 --- /dev/null +++ b/docs/sphinx/source/conf.py.in @@ -0,0 +1,217 @@ +# -*- coding: utf-8 -*- +# +# GNU Radio documentation build configuration file, created by +# sphinx-quickstart on Sun Oct 16 22:27:51 2011. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +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('@CMAKE_CURRENT_SOURCE_DIR@')) +sys.path.insert(0, '@CMAKE_INSTALL_PREFIX@/@GR_PYTHON_DIR@') + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.autosummary', 'gnuradio_sphinx', 'hieroglyph'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'GNU Radio (Unofficial Documentation)' +copyright = u'2011, Gnu Radio Developers' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = 'blah.blah' +# The full version, including alpha/beta/rc tags. +release = 'blah.blah.blah' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'GNURadiodoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'GNURadio.tex', u'GNU Radio Documentation', + u'Gnu Radio Developers', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'gnuradio', u'GNU Radio Documentation', + [u'Gnu Radio Developers'], 1) +] -- cgit From 18fccf6e204693dd0474c9ef23b8a4c0b70cb0f2 Mon Sep 17 00:00:00 2001 From: Tom Rondeau Date: Sun, 20 May 2012 13:37:30 -0400 Subject: sphinx: dummy toctree entries to remove warnings. --- docs/sphinx/source/index.rst | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) 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 gnuradio.video_sdl gnuradio.vocoder + + +.. Use this to add to the toctree but not displayed +.. It's mostly to get rid of warnings + +.. toctree:: + :hidden: + + coding + converter + demodulation + dft + filter + filter_design + internal + level + math + misc + misc + modulation + sink + slicedice + source + sync + top_block + + atsc_blks + blks + blks2_utilities + digital_blocks + constellations + ofdm + pkt_utils + digital_utilities + optfir + pager_blks + pyqt_filter + pyqt_plot + trellis_blks + trellis_objs + vocoder_blks + window_detail + wxgui_blks -- cgit From 6977392abb2e5ccb54c4f23c271ee84d40fb5c72 Mon Sep 17 00:00:00 2001 From: Tom Rondeau Date: Sun, 20 May 2012 13:39:59 -0400 Subject: docs: fixing up docs from sphinx warnings. --- gr-digital/include/digital_cma_equalizer_cc.h | 4 ++-- gr-digital/include/digital_constellation_receiver_cb.h | 6 +++--- gr-digital/include/digital_fll_band_edge_cc.h | 4 ++-- gr-digital/include/digital_kurtotic_equalizer_cc.h | 4 ++-- gr-digital/include/digital_mpsk_receiver_cc.h | 8 ++++---- 5 files changed, 13 insertions(+), 13 deletions(-) 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 -- cgit From 91c3d95daa974fbbab11ac26a3a30c11ca35a5cd Mon Sep 17 00:00:00 2001 From: Tom Rondeau Date: Sun, 20 May 2012 13:59:35 -0400 Subject: sphinx: Added a README for explaining the documentation process. --- docs/sphinx/README | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/sphinx/README 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. + -- cgit