Merge pull request #542 from paulromano/readthedocs

Documentation changes to build on Read The Docs

.gitignore

@@ -24,6 +24,7 @@ examples/python/**/*.xml
 # Documentation builds
 docs/build
 docs/source/_images/*.pdf
+docs/source/_images/*.aux
 
 # Source build
 build

docs/Makefile

@@ -17,6 +17,8 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou
 SVG2PDF = inkscape
 PDFS    = $(patsubst %.svg,%.pdf,$(wildcard $(IMAGEDIR)/*.svg))
 
+# Tikz to PNG conversion
+PNGS = $(patsubst %.tex,%.png,$(wildcard $(IMAGEDIR)/*.tex))
 
 .PHONY: help images clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
 
@@ -43,8 +45,13 @@ help:
 %.pdf: %.svg
 	$(SVG2PDF) -f $< -A $@
 
+%.png: %.tex
+	pdflatex --interaction=nonstopmode --output-directory=$(IMAGEDIR) $<
+	pdftoppm -r 120 -singlefile $(patsubst %.tex,%.pdf, $<) $(basename $<)
+	convert -trim -fuzz 2% -transparent white $(patsubst %.tex,%.ppm,$<) $@
+
 # Rule to build PDFs
-images: $(PDFS)
+images: $(PDFS) $(PNGS)
 
 clean:
 	-rm -rf $(BUILDDIR)/*

docs/requirements-rtd.txt

@@ -0,0 +1,2 @@
+sphinx-numfig
+jupyter

docs/source/methods/cmfd_tikz/cmfd_flow.tikz → docs/source/_images/cmfd_flow.tex

@@ -1,3 +1,12 @@
+\documentclass{standalone}
+\usepackage[utf8]{inputenc}
+\usepackage{amsmath}
+\usepackage{tikz}
+\usepackage{pgfplots}
+\pgfplotsset{compat=1.11}
+\usetikzlibrary{shapes,snakes,shadows,arrows,calc,decorations.markings,patterns,fit,matrix,spy}
+\pagestyle{empty}
+\begin{document}
 \begin{tikzpicture}
 	\matrix[every node/.style={draw, thick, minimum width=3cm, minimum height=1cm, align=center}, column sep=2cm, row sep=1cm] (m) {
 \node[draw, fill=red!40] (start) {Batch $i$ \\ tally NDA}; & \\
@@ -16,4 +25,5 @@
 		\draw (modify.north)  --  (end.south);
     \end{scope}
 
-\end{tikzpicture}
+\end{tikzpicture}
+\end{document}

docs/source/methods/cmfd_tikz/meshfig.tikz → docs/source/_images/meshfig.tex

@@ -1,10 +1,20 @@
+\documentclass[tikz]{standalone}
+\usepackage[utf8]{inputenc}
+\usepackage{amsmath}
+\usepackage{tikz}
+\usepackage{pgfplots}
+\pgfplotsset{compat=1.11}
+\usetikzlibrary{shapes,snakes,shadows,arrows,calc,decorations.markings,patterns,fit,matrix,spy}
+\usepackage{fixltx2e}
+\pagestyle{empty}
+\begin{document}
 
     % these dimensions are determined in arrow_dimms.ods
 
     \def\scale{1.0}
 
     \def\latWidth{0.2808363589*\scale}
-    
+
     \def\RPVOR{3*\scale}
     \def\rectW{0.75*\scale}
     \def\RPVIR{2.8694005485*\scale}
@@ -20,7 +30,7 @@
     \def\bafMIRy{1.5445999739*\scale}
     \def\bafMORx{1.8544620609*\scale}
     \def\bafMORy{1.573625702*\scale}
-    
+
     \tikzset{Assembly/.style={
         inner sep=0pt,
         text width=\latWidth in,
@@ -29,13 +39,13 @@
         align=center
         }
     }
-    
+
     \def\tkzRPV{(0,0) circle (\RPVIR) (0,0) circle (\RPVOR)}
     \def\tkzBarrel{(0,0) circle (\BarrelIR) (0,0) circle (\BarrelOR)}
     \def\tkzShields{(0,0) circle (\BarrelOR) (0,0) circle (\ShieldOR)}
-    
+
     \def\tkzBaffCOR{(-\bafCORx, -\bafCORy) rectangle (\bafCORx, \bafCORy)}
-    \def\tkzBaffCIR{(-\bafCIRx, -\bafCIRy) rectangle (\bafCIRx, \bafCIRy)} 
+    \def\tkzBaffCIR{(-\bafCIRx, -\bafCIRy) rectangle (\bafCIRx, \bafCIRy)}
     \def\tkzBaffMOR{(-\bafMORx, -\bafMORy) rectangle (\bafMORx, \bafMORy)}
     \def\tkzBaffMIR{(-\bafMIRx, -\bafMIRy) rectangle (\bafMIRx, \bafMIRy) }
     \def\tkzBaffleC{ \tkzBaffCIR \tkzBaffCOR }
@@ -53,17 +63,17 @@
       \begin{tikzpicture}[x=1in,y=1in, xshift=3in]
 \scalebox{0.6}{
         % draw RPV, barrel, and shield panels
-        
+
         \path[fill=black,even odd rule] \tkzRPV;
         \path[fill=black,even odd rule] \tkzBarrel;
         \begin{scope}
           \clip[rotate around={45:(0,0)}] (-\RPVOR, -\rectW) rectangle (\RPVOR, \rectW) (-\rectW, \RPVOR) rectangle (\rectW, -\RPVOR);
           \path[fill=black,even odd rule] \tkzShields;
         \end{scope}
 
-        
+
         % draw assembly row/column headers
-        
+
         \draw[red, thick] ($(-7*\latWidth,\RPVOR/\latWidth*\latWidth)$) node[above, anchor=south] {R} -- ($(-7*\latWidth,4*\latWidth)$);
         \draw[red, thick] ($(-6*\latWidth,\RPVOR/\latWidth*\latWidth)$) node[above, anchor=south] {P} -- ($(-6*\latWidth,6*\latWidth)$);
         \draw[red, thick] ($(-5*\latWidth,\RPVOR/\latWidth*\latWidth)$) node[above, anchor=south] {N} -- ($(-5*\latWidth,7*\latWidth)$);
@@ -79,7 +89,7 @@
         \draw[red, thick] ($(5*\latWidth,\RPVOR/\latWidth*\latWidth)$) node[above, anchor=south] {C} -- ($(5*\latWidth,7*\latWidth)$);
         \draw[red, thick] ($(6*\latWidth,\RPVOR/\latWidth*\latWidth)$) node[above, anchor=south] {B} -- ($(6*\latWidth,6*\latWidth)$);
         \draw[red, thick] ($(7*\latWidth,\RPVOR/\latWidth*\latWidth)$) node[above, anchor=south] {A} -- ($(7*\latWidth,4*\latWidth)$);
-        
+
         \begin{scope}[rotate=90]
           \draw[red, thick] ($(-7*\latWidth,\RPVOR/\latWidth*\latWidth)$) node[left, anchor=east] {15} -- ($(-7*\latWidth,4*\latWidth)$);
           \draw[red, thick] ($(-6*\latWidth,\RPVOR/\latWidth*\latWidth)$) node[left, anchor=east] {14} -- ($(-6*\latWidth,6*\latWidth)$);
@@ -97,7 +107,7 @@
           \draw[red, thick] ($(6*\latWidth,\RPVOR/\latWidth*\latWidth)$) node[left, anchor=east] {2} -- ($(6*\latWidth,6*\latWidth)$);
           \draw[red, thick] ($(7*\latWidth,\RPVOR/\latWidth*\latWidth)$) node[left, anchor=east] {1} -- ($(7*\latWidth,4*\latWidth)$);
         \end{scope}
-        
+
         % draw fuel assembly nodes
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($(-8*\latWidth,8*\latWidth)$) {};
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($(-7*\latWidth,8*\latWidth)$) {};
@@ -116,7 +126,7 @@
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($( 6*\latWidth,8*\latWidth)$) {};
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($( 7*\latWidth,8*\latWidth)$) {};
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($( 8*\latWidth,8*\latWidth)$) {};
-        
+
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($(-8*\latWidth,7*\latWidth)$) {};
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($(-7*\latWidth,7*\latWidth)$) {};
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($(-6*\latWidth,7*\latWidth)$) {};
@@ -581,7 +591,7 @@
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($( 6*\latWidth,-7*\latWidth)$) {};
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($( 7*\latWidth,-7*\latWidth)$) {};
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($( 8*\latWidth,-7*\latWidth)$) {};
-        
+
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($(-8*\latWidth,-8*\latWidth)$) {};
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($(-7*\latWidth,-8*\latWidth)$) {};
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($(-6*\latWidth,-8*\latWidth)$) {};
@@ -601,7 +611,7 @@
         \node [Assembly, fill=\lightgray, opacity=0.3] at ($( 8*\latWidth,-8*\latWidth)$) {};
 
         % draw baffle north/south
-        
+
         \begin{scope}[even odd rule]
           \clip[rotate=90] \tkzBaffMClip;
           \path[fill=black] \tkzBaffleC;
@@ -611,9 +621,9 @@
           \clip \tkzBaffMClip;
           \path[fill=black, rotate=90] \tkzBaffleM;
         \end{scope}
-        
+
         % draw baffle east/west
-        
+
         \begin{scope}[rotate=90]
           \begin{scope}[even odd rule]
             \clip[rotate=90] \tkzBaffMClip;
@@ -626,3 +636,4 @@
           \end{scope}
         \end{scope}}
       \end{tikzpicture}
+\end{document}

docs/source/conf.py

@@ -13,6 +13,26 @@
 
 import sys, os
 
+# Determine if we're on Read the Docs server
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+# On Read the Docs, we need to mock a few third-party modules so we don't get
+# ImportErrors when building documentation
+try:
+    from unittest.mock import MagicMock
+except ImportError:
+    from mock import Mock as MagicMock
+
+
+class Mock(MagicMock):
+    @classmethod
+    def __getattr__(cls, name):
+        return Mock()
+
+MOCK_MODULES = ['numpy', 'h5py', 'pandas', 'opencg']
+sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
+
+
 # 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.
@@ -26,9 +46,8 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.napoleon',
-              'sphinx.ext.pngmath',
+              'sphinx.ext.mathjax',
               'sphinx.ext.autosummary',
-              'sphinxcontrib.tikz',
               'sphinx_numfig',
               'notebook_sphinxext']
 
@@ -105,16 +124,15 @@
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'haiku'
-#html_theme = 'altered_nature'
-#html_theme = 'sphinxdoc'
-
-# 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 = {'full_logo': True,
-                      'linkcolor': '#0c3762',
-                      'visitedlinkcolor': '#0c3762'}
+if on_rtd:
+    html_theme = 'default'
+    html_logo = '_images/openmc200px.png'
+else:
+    html_theme = 'haiku'
+    html_theme_options = {'full_logo': True,
+                          'linkcolor': '#0c3762',
+                          'visitedlinkcolor': '#0c3762'}
+    html_logo = '_images/openmc.png'
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = ["_theme"]
@@ -126,10 +144,6 @@
 # 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 = '_images/openmc.png'
-
 # 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.

docs/source/devguide/docbuild.rst

@@ -12,15 +12,8 @@ is via pip:
 
     sudo pip install sphinx
 
-Additionally, you will also need two Sphinx extensions for TikZ support and
-numbering figures. The sphinxcontrib-tikz_ package should be installed directly
-from the git repository as such:
-
-.. code-block:: sh
-
-   sudo pip install https://bitbucket.org/philexander/tikz/get/HEAD.tar.gz
-
-The Numfig_ package can be installed directly with pip:
+Additionally, you will also need a Sphinx extension for numbering figures. The
+Numfig_ package can be installed directly with pip:
 
 .. code-block:: sh
 

docs/source/methods/cmfd.rst

@@ -110,10 +110,12 @@ illustrated as a flow chart below. After a batch of neutrons
 is simulated, NDA can take place. Each of the steps described above is described
 in detail in the following sections.
 
-.. tikz:: Flow chart of NDA process. Note "XS" is used for cross section and
-          "DC" is used for diffusion coefficient.
-   :libs: shapes, snakes, shadows, arrows, calc, decorations.markings, patterns, fit, matrix, spy
-   :include: cmfd_tikz/cmfd_flow.tikz
+.. figure:: ../_images/cmfd_flow.png
+    :align: center
+    :figclass: align-center
+
+    Flow chart of NDA process. Note "XS" is used for cross section and "DC" is
+    used for diffusion coefficient.
 
 Calculation of Macroscopic Cross Sections
 -----------------------------------------
@@ -422,9 +424,11 @@ during the MC simulation with incoming and outgoing partial currents. This
 allows the user to not have to worry about neutrons producing adequate tallies
 in mesh cells far away from the core.
 
-.. tikz:: Diagram of CMFD acceleration mesh
-   :libs: shapes, snakes, shadows, arrows, calc, decorations.markings, patterns, fit, matrix, spy
-   :include: cmfd_tikz/meshfig.tikz
+.. figure:: ../_images/meshfig.png
+    :align: center
+    :figclass: align-center
+
+    Diagram of CMFD acceleration mesh
 
 During an MC simulation, CMFD tallies are accumulated. The basic tallies needed
 are listed in Table :ref:`tab_tally`. Each tally is performed on a spatial and

docs/sphinxext/notebook_sphinxext.py

@@ -12,10 +12,7 @@
 from docutils.parsers.rst.roles import set_classes
 from docutils.transforms import misc
 
-try:
-    from IPython.nbconver.exporters import html
-except ImportError:
-    from IPython.nbconvert import html
+from nbconvert import html
 
 
 class Notebook(Directive):