Merge pull request #114 from daft-dev/docs

Updating docs to build on ReadTheDocs
daft-dev · Sep 15, 2019 · 894164c · 894164c
2 parents 8f55115 + 68f61d5
commit 894164c
Show file tree

Hide file tree

Showing 49 changed files with 278 additions and 189 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -2,6 +2,14 @@ language: python
 python:
   - "3.6"
   - "3.7"
+addons:
+  apt:
+    packages:
+      - texlive-latex-recommended
+      - texlive-latex-extra
+      - texlive-fonts-recommended
+      - texlive-fonts-extra
+      - dvipng
 # command to install dependencies
 install:
   - pip install -r dev-requirements.txt
@@ -10,3 +18,15 @@ install:
 script:
   - flake8 config=.flake8
   - pytest
+after_success: |
+  echo $TRAVIS_PYTHON_VERSION
+  if [ "$TRAVIS_PULL_REQUEST" = "false" ] && [ -n "$GITHUB_API_KEY" ] &&  [ "$TRAVIS_PYTHON_VERSION" = "3.7" ] ; then
+    cd $TRAVIS_BUILD_DIR
+    git checkout $TRAVIS_BRANCH
+    python docs/gen_example.py
+    git add docs/_static/examples docs/examples
+    git -c user.name='daft-bot' -c user.email='foreman.mackey+daft-bot@gmail.com' commit -m "updating examples [ci skip]"
+    git push https://$GITHUB_USER_NAME:$GITHUB_API_KEY@github.com/$TRAVIS_REPO_SLUG $TRAVIS_BRANCH
+  fi
+
+
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1 +1 @@
-include README.rst LICENSE.rst
+include README.rst LICENSE.rst requirements.txt
diff --git a/daft.py b/daft.py
@@ -319,7 +319,7 @@ def add_plate(
     def add_text(self, x, y, label, fontsize=None):
         """
         A subclass of plate to writing text using grid coordinates. Any
-        **kwargs are passed through to :class:`PGM.Plate`.
+        ``**kwargs`` are passed through to :class:`PGM.Plate`.
 
         :param x:
             The x-coordinate of the text in *model units*.
@@ -449,9 +449,9 @@ def show(self, dpi=None, *args, **kwargs):
 
     def savefig(self, fname, *args, **kwargs):
         """
-        Wrapper on `matplotlib.Figure.savefig()` that sets default image
-        padding using `bbox_inchaes = tight`.
-        `*args` and **kwargs` are passed to `matplotlib.Figure.savefig()`.
+        Wrapper on ``matplotlib.Figure.savefig()`` that sets default image
+        padding using ``bbox_inchaes = tight``.
+        ``*args`` and ``**kwargs`` are passed to `matplotlib.Figure.savefig()`.
 
         :param fname:
             The filename to save as.
@@ -735,15 +735,18 @@ def get_frontier_coord(self, target_xy, ctx, edge):
         contain the same `x` and `y` coordinates. See the example of rectangle
         below:
 
-                    _____________
-                    |            |    ____--X (target_node)
-                    |        __--X----
-                    |     X--    |(return coordinate of this point)
-                    |            |
-                    |____________|
+        .. code-block:: python
+
+            _____________
+            |            |    ____--X (target_node)
+            |        __--X----
+            |     X--    |(return coordinate of this point)
+            |            |
+            |____________|
 
         :target_xy: (x float, y float)
             A tuple of coordinate of target node
+
         """
 
         # Scale the coordinates appropriately.

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,3 +1,2 @@
 _build
 !*.png
-_static/examples/*.png
diff --git a/docs/_static/examples.js b/docs/_static/examples.js
@@ -16,22 +16,22 @@ function shuffle(array) {
     return array;
 }
 
-function show_examples(N) {
-    d3.json("/_static/examples.json", function (examples) {
+function show_examples(static_path, examples_path, N) {
+    d3.json(static_path + "/examples.json", function (examples) {
         var k, names = [];
         for (k in examples) {
             names.push(k);
         }
 
-        if (typeof(N) !== "undefined")
+        if (typeof (N) !== "undefined")
             names = shuffle(names).slice(0, N);
 
         d3.select("#examples").selectAll(".example")
-                .data(names)
+            .data(names)
             .enter().append("a")
-                .attr("class", "example")
-                .attr("href", function (d) { return "/examples/" + d + "/"; })
+            .attr("class", "example")
+            .attr("href", function (d) { return examples_path + "/" + d + "/"; })
             .append("img")
-                .attr("src", function (d) { return "/_static/examples/" + d + "-thumb.png"; });
+            .attr("src", function (d) { return static_path + "/examples/" + d + "-thumb.png"; });
     });
 }
diff --git a/docs/_static/examples.json b/docs/_static/examples.json
@@ -1,14 +1,46 @@
 {
-    "classic":         [ 60, 25],
-    "nogray":          [ 60, 25],
-    "nocircles":       [167, 120],
-    "wordy":           [167, 120],
-    "weaklensing":     [220, 110],
-    "mrf":             [ 37, 37],
-    "exoplanets":      [142, 155],
-    "badfont":         [ 20, 25],
-    "recursive":       [252, 365],
-    "astronomy":       [80, 170],
-    "deconvolution":   [660, 70],
-    "fixed":           [5, 50]
-}
+    "classic": [
+        60,
+        25
+    ],
+    "nogray": [
+        60,
+        25
+    ],
+    "nocircles": [
+        167,
+        120
+    ],
+    "wordy": [
+        167,
+        120
+    ],
+    "weaklensing": [
+        220,
+        110
+    ],
+    "mrf": [
+        37,
+        37
+    ],
+    "exoplanets": [
+        142,
+        155
+    ],
+    "recursive": [
+        252,
+        365
+    ],
+    "astronomy": [
+        80,
+        170
+    ],
+    "deconvolution": [
+        660,
+        70
+    ],
+    "fixed": [
+        5,
+        50
+    ]
+}
diff --git a/docs/_static/examples/astronomy-thumb.png b/docs/_static/examples/astronomy-thumb.png
diff --git a/docs/_static/examples/astronomy.png b/docs/_static/examples/astronomy.png
diff --git a/docs/_static/examples/badfont-thumb.png b/docs/_static/examples/badfont-thumb.png
diff --git a/docs/_static/examples/badfont.png b/docs/_static/examples/badfont.png
diff --git a/docs/_static/examples/classic-thumb.png b/docs/_static/examples/classic-thumb.png
diff --git a/docs/_static/examples/classic.png b/docs/_static/examples/classic.png
diff --git a/docs/_static/examples/deconvolution-thumb.png b/docs/_static/examples/deconvolution-thumb.png
diff --git a/docs/_static/examples/deconvolution.png b/docs/_static/examples/deconvolution.png
diff --git a/docs/_static/examples/exoplanets-thumb.png b/docs/_static/examples/exoplanets-thumb.png
diff --git a/docs/_static/examples/exoplanets.png b/docs/_static/examples/exoplanets.png
diff --git a/docs/_static/examples/fixed-thumb.png b/docs/_static/examples/fixed-thumb.png
diff --git a/docs/_static/examples/fixed.png b/docs/_static/examples/fixed.png
diff --git a/docs/_static/examples/mrf-thumb.png b/docs/_static/examples/mrf-thumb.png
diff --git a/docs/_static/examples/mrf.png b/docs/_static/examples/mrf.png
diff --git a/docs/_static/examples/nocircles-thumb.png b/docs/_static/examples/nocircles-thumb.png
diff --git a/docs/_static/examples/nocircles.png b/docs/_static/examples/nocircles.png
diff --git a/docs/_static/examples/nogray-thumb.png b/docs/_static/examples/nogray-thumb.png
diff --git a/docs/_static/examples/nogray.png b/docs/_static/examples/nogray.png
diff --git a/docs/_static/examples/recursive-thumb.png b/docs/_static/examples/recursive-thumb.png
diff --git a/docs/_static/examples/recursive.png b/docs/_static/examples/recursive.png
diff --git a/docs/_static/examples/weaklensing-thumb.png b/docs/_static/examples/weaklensing-thumb.png
diff --git a/docs/_static/examples/weaklensing.png b/docs/_static/examples/weaklensing.png
diff --git a/docs/_static/examples/wordy-thumb.png b/docs/_static/examples/wordy-thumb.png
diff --git a/docs/_static/examples/wordy.png b/docs/_static/examples/wordy.png
diff --git a/docs/_themes/daft/layout.html b/docs/_themes/daft/layout.html
@@ -5,10 +5,10 @@
 {% endif %}
 
 {%- block extrahead %}
-    {{ super() }}
+{{ super() }}
 
-    <link rel="shortcut icon" href="{{ pathto('_static/favicon.png', 1) }}">
-    <link rel="stylesheet" href="{{ pathto('_static/code.css', 1) }}" type="text/css" />
+<link rel="shortcut icon" href="{{ pathto('_static/favicon.png', 1) }}">
+<link rel="stylesheet" href="{{ pathto('_static/code.css', 1) }}" type="text/css" />
 
 {% endblock %}
 
@@ -28,29 +28,29 @@ <h2>{{ theme_tagline }}</h2>
 
 {%- block footer %}
 
-    <div class="footer">
-        Copyright {{ copyright }}. Released under
-            <a href="https://raw.github.com/dfm/daft/master/LICENSE.rst">MIT License</a>.
-    </div>
+<div class="footer">
+    Copyright {{ copyright }}. Released under
+    <a href="https://raw.github.com/daft-dev/daft/master/LICENSE.rst">MIT License</a>.
+</div>
 
-    <a href="https://github.com/dfm/daft" class="github">
-        <img style="position: absolute; top: 0; right: 0; border: 0;"
-            src="https://s3.amazonaws.com/github/ribbons/forkme_right_green_007200.png"
-            alt="Fork me on GitHub" class="github"/>
-    </a>
+<a href="https://github.com/daft-dev/daft" class="github">
+    <img style="position: absolute; top: 0; right: 0; border: 0;"
+        src="https://s3.amazonaws.com/github/ribbons/forkme_right_green_007200.png" alt="Fork me on GitHub"
+        class="github" />
+</a>
 
-    <script type="text/javascript">
+<script type="text/javascript">
 
-        var _gaq = _gaq || [];
-        _gaq.push(['_setAccount', 'UA-35127040-1']);
-        _gaq.push(['_trackPageview']);
+    var _gaq = _gaq || [];
+    _gaq.push(['_setAccount', 'UA-35127040-1']);
+    _gaq.push(['_trackPageview']);
 
-        (function() {
-            var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
-            ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
-            var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
-        })();
+    (function () {
+        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+    })();
 
-    </script>
+</script>
 
-{%- endblock %}
+{%- endblock %}
diff --git a/docs/_themes/daft/static/daft.css b/docs/_themes/daft/static/daft.css
@@ -1,6 +1,6 @@
 @import url("normalize.css");
-@import url(http://fonts.googleapis.com/css?family=Lato:100,300,700,300italic);
-@import url(http://fonts.googleapis.com/css?family=Source+Code+Pro:300,400,600);
+@import url(//fonts.googleapis.com/css?family=Lato:100,300,700,300italic);
+@import url(//fonts.googleapis.com/css?family=Source+Code+Pro:300,400,600);
 
 body {
     font-family: Lato, "Helvetica Neue", Helvetica, sans-serif;

diff --git a/docs/conf.py b/docs/conf.py
@@ -9,7 +9,11 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.mathjax"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -22,7 +26,7 @@
 
 # General information about the project.
 project = u"Daft"
-copyright = u"2012, Dan Foreman-Mackey & David W. Hogg"
+copyright = u"2012-2019, Daft Developers"
 version = daft.__version__
 release = daft.__version__
 
@@ -60,7 +64,9 @@
 # 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 = {"tagline": "Beautifully rendered probabilistic graphical models."}
+html_theme_options = {
+    "tagline": "Beautifully rendered probabilistic graphical models."
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = ["_themes"]
@@ -144,7 +150,7 @@
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
 latex_documents = [
-    ("index", "Daft.tex", u"Daft Documentation", u"Dan Foreman-Mackey \\& David W. Hogg", "manual")
+    ("index", "Daft.tex", u"Daft Documentation", u"Daft Developers", "manual")
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -170,7 +176,7 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [("index", "daft", u"Daft Documentation", [u"Dan Foreman-Mackey & David W. Hogg"], 1)]
+man_pages = [("index", "daft", u"Daft Documentation", [u"Daft Developers"], 1)]
 
 # If true, show URL addresses after external links.
 # man_show_urls = False
@@ -184,7 +190,7 @@
         "index",
         "Daft",
         u"Daft Documentation",
-        u"Dan Foreman-Mackey & David W. Hogg",
+        u"Daft Developers",
         "Daft",
         "One line description of project.",
         "Miscellaneous",

diff --git a/docs/examples/astronomy.rst b/docs/examples/astronomy.rst
@@ -18,22 +18,43 @@ taken.  It is incomplete!
 ::
 
     
+    import daft
     from matplotlib import rc
+    
     rc("font", family="serif", size=12)
     rc("text", usetex=True)
     
-    import daft
     
-    pgm = daft.PGM(grid_unit=4., node_unit=1.4)
+    pgm = daft.PGM(grid_unit=4.0, node_unit=1.4)
     
     # Start with the plates.
-    tweak=0.02
+    tweak = 0.02
     rect_params = {"lw": 2}
-    pgm.add_plate([1.5+tweak, 0.5+tweak, 6.0-2*tweak, 3.75-2*tweak], label=r"\Large telescope+camera+filter multiplets", rect_params=rect_params)
-    pgm.add_plate([2.5+tweak, 1.0+tweak, 4.0-2*tweak, 2.75-2*tweak], label=r"\Large images", rect_params=rect_params)
-    pgm.add_plate([3.5+tweak, 1.5+tweak, 2.0-2*tweak, 1.75-2*tweak], label=r"\Large pixel patches", rect_params=rect_params)
-    pgm.add_plate([1.0+tweak, 4.25+tweak, 3.5-2*tweak, 1.75-2*tweak], label=r"\Large stars", rect_params=rect_params)
-    pgm.add_plate([5.5+tweak, 4.25+tweak, 2.5-2*tweak, 1.75-2*tweak], label=r"\Large galaxies", rect_params=rect_params)
+    pgm.add_plate(
+        [1.5 + tweak, 0.5 + tweak, 6.0 - 2 * tweak, 3.75 - 2 * tweak],
+        label=r"\Large telescope+camera+filter multiplets",
+        rect_params=rect_params,
+    )
+    pgm.add_plate(
+        [2.5 + tweak, 1.0 + tweak, 4.0 - 2 * tweak, 2.75 - 2 * tweak],
+        label=r"\Large images",
+        rect_params=rect_params,
+    )
+    pgm.add_plate(
+        [3.5 + tweak, 1.5 + tweak, 2.0 - 2 * tweak, 1.75 - 2 * tweak],
+        label=r"\Large pixel patches",
+        rect_params=rect_params,
+    )
+    pgm.add_plate(
+        [1.0 + tweak, 4.25 + tweak, 3.5 - 2 * tweak, 1.75 - 2 * tweak],
+        label=r"\Large stars",
+        rect_params=rect_params,
+    )
+    pgm.add_plate(
+        [5.5 + tweak, 4.25 + tweak, 2.5 - 2 * tweak, 1.75 - 2 * tweak],
+        label=r"\Large galaxies",
+        rect_params=rect_params,
+    )
     
     # ONLY pixels are observed
     asp = 2.3
@@ -50,7 +71,7 @@ taken.  It is incomplete!
     # Stars
     pgm.add_node("star patch", r"star patch", 4.0, 3.0, aspect=asp)
     pgm.add_edge("star patch", "true pixels")
-    pgm.add_node("star SED", r"~\\spectral energy\\distribution", 2.5, 4.75, aspect=asp+0.2)
+    pgm.add_node("star SED", r"~\\spectral energy\\distribution", 2.5, 4.75, aspect=asp + 0.2)
     pgm.add_edge("star SED", "star patch")
     pgm.add_node("star position", r"position", 4.0, 4.75, aspect=asp)
     pgm.add_edge("star position", "star patch")
@@ -76,7 +97,7 @@ taken.  It is incomplete!
     # Galaxies
     pgm.add_node("galaxy patch", r"galaxy patch", 5.0, 3.0, aspect=asp)
     pgm.add_edge("galaxy patch", "true pixels")
-    pgm.add_node("galaxy SED", r"~\\spectral energy\\distribution", 6.5, 4.75, aspect=asp+0.2)
+    pgm.add_node("galaxy SED", r"~\\spectral energy\\distribution", 6.5, 4.75, aspect=asp + 0.2)
     pgm.add_edge("galaxy SED", "galaxy patch")
     pgm.add_node("morphology", r"morphology", 7.5, 4.75, aspect=asp)
     pgm.add_edge("morphology", "galaxy patch")
@@ -131,7 +152,7 @@ taken.  It is incomplete!
     pgm.add_node("psf", r"PSF model", 3.0, 3.5, aspect=asp)
     pgm.add_edge("psf", "star patch")
     pgm.add_edge("psf", "galaxy patch")
-    pgm.add_node("optics", r"optics", 2.0, 3.0, aspect=asp-1.2)
+    pgm.add_node("optics", r"optics", 2.0, 3.0, aspect=asp - 1.2)
     pgm.add_edge("optics", "psf")
     pgm.add_edge("optics", "WCS")
     pgm.add_node("atmosphere", r"~\\atmosphere\\model", 1.0, 3.5, aspect=asp)