Merge pull request #44 from QInfer/feature-improved_docs

wip improving documentation
QInfer · May 31, 2016 · 5d81df4 · 5d81df4
2 parents f655bcf + 0594d4a
commit 5d81df4
Show file tree

Hide file tree

Showing 25 changed files with 219 additions and 268 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -22,21 +22,24 @@ before_install:
   - conda update --yes conda
 
 install:
-  - conda install --yes python=$TRAVIS_PYTHON_VERSION numpy scipy matplotlib scikit-learn
+  - conda install --yes python=$TRAVIS_PYTHON_VERSION numpy scipy matplotlib scikit-learn sphinx
   - pip install -r requirements.txt
   - python setup.py install
   - cd src/
+
 script:
   - py.test --cov-config .coveragerc --cov=qinfer
   - pylint --py3k qinfer/
+  - cd $TRAVIS_BUILD_DIR/doc
+  - make doctest
 
 after_success:
   - coveralls
 
 before_deploy:
   # For why this is needed, see:
   # http://stackoverflow.com/questions/36635650/travisci-deploy-cannot-find-setup-py
-  - cd ~/
+  - cd $TRAVIS_BUILD_DIR
 
 deploy:
   provider: pypi

diff --git a/doc/source/abstract.txt b/doc/source/abstract.txt
@@ -0,0 +1,13 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus ante
+tortor, pulvinar vitae velit ac, rutrum molestie metus. Aliquam consequat dui
+sit amet felis tempus congue. Mauris non ante ut leo malesuada commodo. Nam
+consectetur interdum risus, vel tincidunt ipsum varius sit amet. Praesent
+sagittis, nulla in egestas cursus, turpis mauris fringilla dui, id accumsan
+odio nisi et magna. Interdum et malesuada fames ac ante ipsum primis in
+faucibus. Proin non quam magna. Ut vitae dapibus quam, sit amet tincidunt
+lorem. Ut tempus ante enim, et accumsan enim semper id. Maecenas a euismod
+quam, ac aliquet ipsum. Nullam ipsum felis, tincidunt id dictum in, euismod in
+justo. Phasellus sodales, ipsum eget laoreet congue, lectus sapien accumsan
+lectus, at congue dui tortor ac elit. Praesent viverra bibendum odio eget
+pharetra. Morbi in sollicitudin urna. Suspendisse tristique libero non lacus
+iaculis, sed laoreet enim sollicitudin.
diff --git a/doc/source/apiref/derived_models.rst b/doc/source/apiref/derived_models.rst
@@ -7,7 +7,7 @@
     
 .. _derived_models:
 
-.. currentmodule:: qinfer.derived_models
+.. currentmodule:: qinfer
 
 Derived Models
 ==============

diff --git a/doc/source/apiref/index.rst b/doc/source/apiref/index.rst
@@ -10,7 +10,6 @@
 API Reference
 =============
 
-Contents:
 
 .. toctree::
     :maxdepth: 2

diff --git a/doc/source/apiref/parallel.rst b/doc/source/apiref/parallel.rst
@@ -7,7 +7,7 @@
     
 .. _parallel:
 
-.. currentmodule:: qinfer.parallel
+.. currentmodule:: qinfer
 
 Parallelized Models
 ===================

diff --git a/doc/source/apiref/rb.rst b/doc/source/apiref/rb.rst
@@ -7,7 +7,7 @@
     
 .. _rb:
 
-.. currentmodule:: qinfer.rb
+.. currentmodule:: qinfer
 
 Accelerated Randomized Benchmarking
 ===================================
@@ -19,6 +19,8 @@ Class Reference
 ~~~~~~~~~~~~~~~
 .. autoclass:: RandomizedBenchmarkingModel
     :members:
+
+.. currentmodule:: qinfer.rb
 
 Function Reference
 ~~~~~~~~~~~~~~~~~~

diff --git a/doc/source/apiref/resamplers.rst b/doc/source/apiref/resamplers.rst
@@ -7,7 +7,7 @@
     
 .. _resamplers:
 
-.. currentmodule:: qinfer.resamplers
+.. currentmodule:: qinfer
 
 Resampling Algorithms
 =====================

diff --git a/doc/source/apiref/smc.rst b/doc/source/apiref/smc.rst
@@ -7,7 +7,7 @@
     
 .. _smc:
 
-.. currentmodule:: qinfer.smc
+.. currentmodule:: qinfer
 
 Sequential Monte Carlo
 ======================

diff --git a/doc/source/apiref/test_models.rst b/doc/source/apiref/test_models.rst
@@ -7,7 +7,7 @@
     
 .. _test_models:
 
-.. currentmodule:: qinfer.test_models
+.. currentmodule:: qinfer
 
 Testing Models
 ==============

diff --git a/doc/source/biblo.rst b/doc/source/biblo.rst
@@ -7,15 +7,17 @@
 
 .. _biblo:
 
-Biblography
-===========
+.. only:: not latex
+
+    Biblography
+    ===========
 
 .. [FB12]
-    Ferrie C., Blume-Kohout R. Estimating the bias of a noisy coin.  AIP Conf. Proc. 1443, 14-21 (2012). :doi:`10.1063/1.3703615`. :arxiv:`arXiv:1201.1493`.
+    Ferrie C., Blume-Kohout R. Estimating the bias of a noisy coin.  AIP Conf. Proc. 1443, 14-21 (2012). :doi:`10.1063/1.3703615`. :arxiv:`1201.1493`.
 .. [FGC12]
     Ferrie C., Granade C. E. & Cory D. G. How to best sample a periodic probability distribution, or on the accuracy of Hamiltonian finding strategies. Quantum Information Processing (2012). :doi:`10.1007/s11128-012-0407-6`. :arxiv:`1110.3067`.
 .. [FG13]
-    Ferrie C., Granade C. E. Likelihood-free parameter estimation. :arxiv:`http://arxiv.org/abs/1304.5828`
+    Ferrie C., Granade C. E. Likelihood-free parameter estimation. :arxiv:`1304.5828`
 .. [Fer14]
     Ferrie C. High posterior density ellipsoids of quantum states. New Journal of Physics. **16** 023006 (2014). :doi:`10.1088/1367-2630/16/2/023006`. :arxiv:`1310.1903`.
 .. [GFWC12]

diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -60,6 +60,7 @@ def __getattr__(cls, name):
         sys.modules[mod_name] = Mock() 
 
 ###############################################################################
+
 import sys, os
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -69,6 +70,9 @@ def __getattr__(cls, name):
 
 # The LaTeX preamble is placed here so that it can be used both by pngmath
 # and by the LaTeX output plugin.
+with open('abstract.txt', 'r') as f:
+    abstract = f.read()
+
 preamble = r"""
 \usepackage{amsfonts}
 \usepackage{bbm}
@@ -77,7 +81,56 @@ def __getattr__(cls, name):
 \newcommand{\Tr}{\mathrm{Tr}}
 \newcommand{\ident}{\mathbbm{1}}
 \newcommand{\ave}{\mathrm{ave}}
-"""
+
+\makeatletter
+\renewcommand{\maketitle}{%
+  \begin{titlepage}%
+    \let\footnotesize\small
+    \let\footnoterule\relax
+    \rule{\textwidth}{1pt}%
+    \ifsphinxpdfoutput
+      \begingroup
+      % These \defs are required to deal with multi-line authors; it
+      % changes \\ to ', ' (comma-space), making it pass muster for
+      % generating document info in the PDF file.
+      \def\\{, }
+      \def\and{and }
+      \pdfinfo{
+        /Author (\@author)
+        /Title (\@title)
+      }
+      \endgroup
+    \fi
+    \begin{flushright}%
+      \sphinxlogo%
+      {\rm\Huge\py@HeaderFamily \@title \par}%
+      % {\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par}
+      \vfill
+      {\LARGE\py@HeaderFamily
+        \begin{tabular}[t]{c}
+          \@author
+        \end{tabular}
+        \par}
+      \vfill
+      {\large
+       \@date \par
+       \vfill
+       \py@authoraddress \par
+      }%
+      {\bf\sffamily ABSTRACT }
+
+      ABSTRACT_HERE%
+      \vfill
+    \end{flushright}%\par
+    \@thanks
+  \end{titlepage}%
+  %\cleardoublepage%
+  \setcounter{footnote}{0}%
+  \let\thanks\relax\let\maketitle\relax
+  %\gdef\@thanks{}\gdef\@author{}\gdef\@title{}
+}
+\makeatother
+""".replace("ABSTRACT_HERE", abstract)
 
 # -- General configuration -----------------------------------------------------
 
@@ -109,9 +162,9 @@ def __getattr__(cls, name):
 # built documents.
 #
 # The short X.Y version.
-version = '0.1a1'
+version = '1.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.1a1'
+release = '1.0b4'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -239,8 +292,8 @@ def __getattr__(cls, name):
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'QInfer.tex', u'QInfer Documentation',
-   u'Christopher Ferrie and Christopher Granade', 'manual'),
+  ('index', 'QInfer.tex', u'QInfer: Bayesian Inference for Quantum Information',
+   u'Christopher Granade and Christopher Ferrie', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -264,8 +317,17 @@ def __getattr__(cls, name):
 #latex_appendices = []
 
 # If false, no module index is generated.
-#latex_domain_indices = True
+latex_domain_indices = False
+
 
+# latex_elements = {
+#     'maketitle': r"""
+# \begin{abstract}
+# Lorem ipsum
+# \end{abstract}
+# \maketitle
+# """
+# }
 
 # -- Options for manual page output --------------------------------------------
 
@@ -322,7 +384,7 @@ def __getattr__(cls, name):
 
 extlinks = {
     'arxiv': ('http://arxiv.org/abs/%s', 'arXiv:'),
-    'doi': ('http://dx.doi.org/abs/%s', 'doi:'),
+    'doi': ('https://dx.doi.org/%s', 'doi:'),
 }
 
 ## OTHER CONFIGURATION PARAMETERS ##############################################
@@ -331,10 +393,11 @@ def __getattr__(cls, name):
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'http://docs.python.org/': None,
-    'numpy': ('http://docs.scipy.org/doc/numpy',None),
-    'IPython': ('http://ipython.org/ipython-doc/stable/', None),
-    'ipyparallel': ('http://ipyparallel.readthedocs.org/en/latest/', None)
+    'https://docs.python.org/3/': None,
+    'numpy': ('https://docs.scipy.org/doc/numpy',None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference',None),
+    'IPython': ('https://ipython.org/ipython-doc/stable/', None),
+    'ipyparallel': ('https://ipyparallel.readthedocs.io/en/latest/', None)
 }
 
 autodoc_member_order = 'bysource'

diff --git a/doc/source/examples/index.rst b/doc/source/examples/index.rst