diff options
Diffstat (limited to 'docs/sphinx')
| -rw-r--r-- | docs/sphinx/CMakeLists.txt | 35 | ||||
| -rw-r--r-- | docs/sphinx/Makefile | 130 | ||||
| -rw-r--r-- | docs/sphinx/README | 38 | ||||
| -rw-r--r-- | docs/sphinx/run_sphinx_build.sh.in | 7 | ||||
| -rw-r--r-- | docs/sphinx/source/conf.py.in (renamed from docs/sphinx/source/conf.py) | 3 | ||||
| -rw-r--r-- | docs/sphinx/source/index.rst | 43 |
6 files changed, 125 insertions, 131 deletions
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> |