Install docs rework (cyclus#206)

* Clean install docs (cyclus#200) * rewrite of main install instructions linked off of front page. Created place-holder for tarball instructions. Several other detailed instruction pages need to be updated or edited * changed both guides to have new install instructions link * added tutorials to main page menu on left, and made Quick Start its own highlighted section * reshape conda install * optimising chape * add debian package isntallation in binarie install * add dependencies warning, + cleaning * typo/syntax * update Getting started Page * reshare Getting started page * spelling correction on binary installation * add root access warning * reorder conda * including instllation from source into tarball install * start tarball installation * start shaping install from source * improving install.rst * first addition of install from git * add seperated files for source compilation and unit testing (cyclus#201) * add Debian package description * add template file with unit test use description * use template file for unit_test description * inprove test_description * update test_unit description * reshape install cyclus, first start for install cycamore * update cycamore and cyclus install file * add table of content and unit test to tarball install and git install * add github link for the tarball * add hook on CYCLUS INSTALL from github, and integrate it into the INSTALL file * fix install bonary * add dependency grab * general editing and formatting (cyclus#203) thx @mbmcgarry * update gitignore * uniformisation * intergration of cycamore repo INSTALL file * include @scopatz comments * update conda installation * add cycamore in the line * shaope SS * small change * a few edits * update sed usage to GNU sed * now hook cyclus/develop repos not BaaaaM/readme * add wget in fuelcycle.org-deps docker container * remove un-needed quote * test include flag * now use flag to include file from cyclus and cycamore repos * fix flag name grab release version from Cyclus and cycamore repos * Idr pphw (cyclus#209) looks good thank @gonuke * fix link * move cyclist tuto at the end of cyclist install * tmp modif * Idr pphw (cyclus#209) looks good thank @gonuke * update ignore list * fix DEPENDENCY hook * add variable to set branch to hook with master as default * remove DEPENDENCY.rst * add FORK variable * wget DEPENDENCIES from Cycamore as well * Include info from Cycamore repo for binary install. * fix dependency file name * replace sed with link at end of file * Update Authors and License * Update footer copyright date * Add BAM to front page and fix formatting on installation page * No longer have separate/detailed conda docs * Ignore more wget content * reduce verbosity of wget * Clean up warnings and errors * more RST errors * Mbm edits (cyclus#219) great! thx @mbmcgarry * Rwcarlsen upd release (cyclus#218) * add new storage and mixer archetypes to site docs * add CYCLUS_NO_CATCH explanation to archetype debugging * add internal annotation descrip and agentversion tables * add draft release notes * fix typos * mention new archetypes * update cyclus/cycamore change description * adding cymetric updates for v1.4 (cyclus#2) * Debugging * update stats * english correction * english correction * update information about v1.4 * update release date + rc link * add v1.4.1 with updated author list * updating DOI * update cyemtric DOI and cycamore author * adding missing authors * add missing author * u14 deprecation * update to 1.5 * update website * f add mbmcgarry comment * f add mbmcgarry comment (bis)
mbmcgarry · Dec 13, 2016 · b672af0 · b672af0
1 parent 701d5ca
commit b672af0
Show file tree

Hide file tree

Showing 32 changed files with 725 additions and 116 deletions.
diff --git a/.gitignore b/.gitignore
@@ -4,4 +4,8 @@ build
 *~
 *.pyc
 gh-build
-source/arche/dbtypes.js
+source/arche/dbtypes.js
+source/user/CYCLUS_INSTALL.rst
+source/user/CYCAMORE_INSTALL.rst
+source/user/DEPENDENCIES.rst
+source/user/CYCAMORE_DEPS.rst
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -2,6 +2,8 @@ Robert Carlsen
 Robert Flanagan
 Matthew Gidden
 Katy Huff
+Meghan McGarry
+Baptiste Mouginot
 Arielle Opotowsky
 Olzhas Rakhimov
 Anthony Scopatz

diff --git a/LICENSE.rst b/LICENSE.rst
@@ -3,7 +3,7 @@ LICENSE
 *******
 ::
 
-    Copyright (c) 2010-2013, University of Wisconsin Computational Nuclear Engineering Research Group
+    Copyright (c) 2010-2016, University of Wisconsin Computational Nuclear Engineering Research Group
      All rights reserved.
     
     Redistribution and use in source and binary forms, with or without

diff --git a/Makefile b/Makefile
@@ -12,6 +12,9 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = ./gh-build
+GIT_BRANCH    = master
+GIT_FORK      = cyclus
+
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -56,6 +59,11 @@ gh-clean gh-revert clean:
 	-rm -rf $(BUILDDIR)
 
 gh-preview html:
+	wget -nv https://raw.githubusercontent.com/${GIT_FORK}/cyclus/${GIT_BRANCH}/INSTALL.rst -O source/user/CYCLUS_INSTALL.rst
+	wget -nv https://raw.githubusercontent.com/${GIT_FORK}/cyclus/${GIT_BRANCH}/DEPENDENCIES.rst -O source/user/DEPENDENCIES.rst
+	wget -nv https://raw.githubusercontent.com/${GIT_FORK}/cycamore/${GIT_BRANCH}/INSTALL.rst -O source/user/CYCAMORE_INSTALL.rst
+	wget -nv https://raw.githubusercontent.com/${GIT_FORK}/cycamore/${GIT_BRANCH}/DEPENDENCIES.rst -O source/user/CYCAMORE_DEPS.rst
+
 	PYTHONDONTWRITEBYTECODE="TRUE" $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)
 	sed -i.bak 's/function top_offset([$$]node){ return [$$]node\[0\].getBoundingClientRect().top; }/function top_offset($$node){ return (typeof $$node[0] === "undefined") ? 0 : $$node[0].getBoundingClientRect().top; }/' ./gh-build/_static/cloud.js
 	sed -i.bak 's/  if (state == "collapsed"){/  if (typeof state === "undefined") {\n	var state = "uncollapsed";\n  };\n  if (state == "collapsed"){/' ./gh-build/_static/cloud.js

diff --git a/docker/fuelcycle.org-deps/Dockerfile b/docker/fuelcycle.org-deps/Dockerfile
@@ -1,6 +1,8 @@
 
 FROM cyclus/cymetric
 
+RUN apt-get update
+RUN apt-get install -y --force-yes wget
 RUN apt-get install -y --force-yes python3-pip
 RUN pip3 install sphinx sphinxcontrib-bibtex
 RUN pip3 install cloud-sptheme==1.6

diff --git a/source/arche/cycpp.rst b/source/arche/cycpp.rst
@@ -126,6 +126,11 @@ contains a listing of all special keys and their meanings.
                  post-process.
     default      The default value for this variable that is used if otherwise 
                  unspecified. The value must match the type of the variable.
+    internal     ``True`` if this state variable is only for
+                 archetype-internal usage.  Although the variable will still
+                 be persisted in the database and initialized normally (e.g.
+                 with any default), it will not be included in the XML schema
+                 or input file.
     shape        The shape of a variable length datatypes. If present this must
                  be a list of integers whose length (rank) makes sense for this
                  type. Specifying positive values will (depending on the 

diff --git a/source/arche/index.rst b/source/arche/index.rst
@@ -37,8 +37,10 @@ To get started please follow the instructions in :doc:`hello_world`.
 Installation
 -------------
 
-Install Cyclus via the instructions on `Github
-<https://github.com/cyclus/cyclus>`_.
+.. toctree::
+    :maxdepth: 1
+
+    ../user/install
 
 Hello World
 -----------

diff --git a/source/arche/testing.rst b/source/arche/testing.rst
@@ -1,8 +1,8 @@
 
 .. _testing:
 
-Testing Agents and Modules
-==========================
+Testing and Debugging Archetypes
+================================
 
 Overview
 --------
@@ -315,6 +315,23 @@ details.
 Debugging
 ----------
 
+If exceptions are being thrown when you try to use your archetype in
+simulations, you can turn off Cyclus' main exception handling/catching by
+setting the environment variable ``CYCLUS_NO_CATCH=1`` when you run cyclus.
+This will prevent exceptions from being caught resulting in a core-dump.  You
+can then use a debugger (e.g. gdb or lldb) to run the failing simulation and
+investigate the source of the crash in more detail.  Something like this:
+
+.. code-block:: bash
+
+    $ CYCLUS_NO_CATCH=1 gdb --args cyclus my-failing-sim.xml
+    
+    GNU gdb (GDB) 7.11
+    Copyright (C) 2016 Free Software Foundation, Inc.
+    ...
+    (gdb) run
+    ...
+
 Cyclus has the ability to dump extra information about a simulation run's
 resource exchange into the database.  This information can be
 particularly helpful for debugging and verifying your archetype's behavior
@@ -352,3 +369,5 @@ The database will then contain two extra tables with several columns each:
 Note that some information about bids can be inferred from corresponding
 requests.  A bid's time, commodity, resource type, and units are all identical
 to those of the corresponding request.
+
+
diff --git a/source/arche/toolkit.rst b/source/arche/toolkit.rst
@@ -41,7 +41,7 @@ following ways:
     #pragma cyclus var {'capacity': 'buf_cap'}
     cyclus::toolkit::ResourceBuff mybuf;
 
-You can read the `API documentation
+You can read the `ResourceBuff API documentation
 <http://fuelcycle.org/cyclus/api/classcyclus_1_1toolkit_1_1ResourceBuff.html>`_ for
 more details on how to use the buffer.
 
@@ -73,7 +73,7 @@ you must annotate the buffer member variable with a Cyclus pre-processor
     #pragma cyclus var {'capacity': 'buf_cap'}
     cyclus::toolkit::ResBuf<cyclus::Material> mybuf;
 
-You can read the `API documentation
+You can read the `ResBuf API documentation
 <http://fuelcycle.org/cyclus/api/classcyclus_1_1toolkit_1_1ResBuf.html>`_ for
 more details on how to use the buffer.
 

diff --git a/source/arche/tutorial/testing.rst b/source/arche/tutorial/testing.rst
@@ -126,10 +126,10 @@ After unit tests, the next step to take is testing your archetype in an actual
 simulation. You can find more on the :ref:`testing` page. 
 
 One of the best ways to learn is by example. The Cycamore repository has
-`examples <https://github.com/cyclus/cycamore/tree/develop/tests>`_ of running
-regression tests that include the full execution stack -- read an input file,
-run a simulation, and test an output file. There are also `examples
+`examples of running regression tests <https://github.com/cyclus/cycamore/tree/develop/tests>`_ 
+that include the full execution stack -- read an input file,
+run a simulation, and test an output file. There are also `examples of integration tests
 <https://github.com/cyclus/cycamore/blob/develop/src/enrichment_tests.cc#L54>`_
-of integration tests that utilize the new `MockSim
+that utilize the new `MockSim
 <http://fuelcycle.org/arche/testing.html?highlight=mocksim#testing-resource-exchange>`_
-testing feature in Cyclus.
+testing feature in Cyclus.
diff --git a/source/atemplates/layout.html b/source/atemplates/layout.html
@@ -4,9 +4,12 @@
   <div class="sphinxlocaltoc">
   <h3>{{ _('Useful Pages') }}</h3>
     <ul><li><ul>
+    <li><a href="/user/install.html">Install Cyclus</a></li>
     <li><a href="/user/index.html">User Guide</a></li>
+    <li><a href="/user/tutorial/index.html">User Tutorial</a></li>
     <li><a href="/arche/index.html">Archetype Developer Guide</a></li>
-    <li><a href="http://fuelcycle.org/cyclus/api/">Cyclus API Documentation</a></li>
+    <li><a href="/arche/tutorial/index.html">Archetype Developer Tutorial</a></li>
+     <li><a href="http://fuelcycle.org/cyclus/api/">Cyclus API Documentation</a></li>
     <li><a href="http://fuelcycle.org/cycamore/api/">Cycamore API Documentation</a></li>
     <li><a href="/basics/glossary.html">Glossary</a></li>
     <li><a href="mailto:[email protected]?subject=Subscribe&body=Send this message to subscribe to the list">Join</a> the 
@@ -18,7 +21,7 @@ <h3>{{ _('Useful Pages') }}</h3>
     {{ super() }}
     <h3>Get Cyclus</h3>
     <br>
-    Current version: <b>1.3.0</b>
+    Current version: <b>1.5.0</b>
     <br><br>
     Install:
     <div class="highlight-bash" style="width:97.5%"><div class="highlight"><pre><span class="nv">$ </span>conda install cyclus cycamore</pre></div></div>

diff --git a/source/cite/citecyc.bib b/source/cite/citecyc.bib
@@ -1,3 +1,30 @@
+@article{cyclus_v1.5,
+author = "Robert Carlsen and Robert Flanagan and Matthew Gidden and Ryan Hodge and Meghan McGarry and Arrielle Opotowsky and Baptiste Mouginot and Anthony Scopatz and Paul Wilson",
+title = "{Cyclus v1.5.0}",
+journal = "figshare",
+year = "2016",
+month = "11",
+url = "https://dx.doi.org/10.6084/m9.figshare.4312643.v2"
+}
+
+@article{cycamore_v1.5,
+author = "Robert Carlsen and Robert Flanagan and Matthew Gidden and Kathryn Huff and Jenny Littell and Meghan McGarry and Baptiste Mouginot and Arrielle Opotowsky and Anthony Scopatz and Steve Skutnik and Paul Wilson",
+title = "{Cycamore v1.5.0}",
+journal = "figshare",
+year = "2016",
+month = "11",
+url = "https://dx.doi.org/10.6084/m9.figshare.4312661.v1"
+}
+
+@article{cymetric_v1.5,
+author = "Robert Carlsen and Matthew Gidden and Ryan Hodge and Baptiste Mouginot and Arrielle Opotowsky and Anthony Scopatz and Paul Wilson",
+title = "{Cymetric v1.5.0}",
+journal = "figshare",
+year = "2016",
+month = "11",
+url = "https://dx.doi.org/10.6084/m9.figshare.4312664.v1"
+}
+
 @article{cyclus_v1.3,
 author = "Robert Carlsen and Robert Flanagan and Matthew Gidden and Kathryn Huff and Meghan McGarry and Arrielle Opotowsky and Anthony Scopatz and Paul Wilson and John Xia",
 title = "{Cyclus v1.3.0}",

diff --git a/source/conf.py b/source/conf.py
@@ -66,7 +66,7 @@
 
 # General information about the project.
 project = u'Cyclus'
-copyright = (u'2012-2014, University of Wisconsin Computational Nuclear '
+copyright = (u'2012-2016, University of Wisconsin Computational Nuclear '
               'Engineering Research Group')
 
 # The version info for the project you're documenting, acts as replacement for

diff --git a/source/index.rst b/source/index.rst
@@ -13,7 +13,6 @@
 
     </div>
 
-.. raw:: html
 
 |cyclus| is the next-generation agent-based nuclear :doc:`fuel cycle simulator
 <basics/fcs_background>`, providing flexibility to users and developers
@@ -27,11 +26,19 @@ developers and encourages them to join a vibrant community in an
 :doc:`expanding ecosystem <basics/ecosystem>`.  Users and developers are
 always welcome and encouraged to use or contribute to the |cyclus| project. 
 
-The |Cyclus| project repository is located at http://github.com/cyclus/cyclus.
+The |Cyclus| project repository is located at http://github.com/cyclus/cyclus
+
+Project repository is located at http://github.com/cyclus/cyclus
+
+Quick Start
+-----------
+:doc:`Get started with Cyclus <user/install>`
 
 News
 -----
 
+**December 13, 2016:** :doc:`Cyclus v1.5.0 is released <previous/v1.5>`
+
 **August 13, 2015:** :doc:`Cyclus included in FY2016 workscopes for the NEUP program <news/fy16neup>`
 
 **July 21-24, 2015:** Joint workshop with CLASS_ project held in Madison, WI
@@ -133,20 +140,30 @@ Contributors
 
 * Denia Djokic
 
+* Royal Elmore
+
 * Robert Flanagan
 
 * `Matthew Gidden <http://mattgidden.com/>`_
 
+* Ryan Hodge
+
 * `Kathryn (Katy) Huff <http://katyhuff.github.io/>`_
 
+* Jenny Littell
+
 * `Meghan McGarry <http://cnerg.github.io/people/mcgarry.html>`_
 
+* `Baptiste Mouginot <http://cnerg.github.com/people/bam.html>`_
+
 * `Arrielle Opotowsky <http://cnerg.github.io/people/opotowsky.html>`_
 
 * Olzhas Rakhimov
 
 * `Anthony Scopatz <http://scopatz.com/>`_
 
+* Steve Skutnik
+
 * Zach Welch
 
 * `Paul Wilson <http://cnerg.github.io/people/pphw.html>`_

diff --git a/source/previous/index.rst b/source/previous/index.rst
@@ -11,6 +11,7 @@ The following are release notes for and links to previously released versions of
 .. toctree::
     :maxdepth: 1
 
+    v1.5
     v1.3
     v1.2
     v1.1
@@ -19,11 +20,21 @@ The following are release notes for and links to previously released versions of
     v0.3
     v0.2
 
+Note: As official 1.4.0 release has been skipped, all the release notes of 1.4.0
+have been included in the 1.5.0.
+
 .. rst-class:: centered
 
 ========= ========== ================ ==============
 Version   Date       Zip              Tar
 ========= ========== ================ ==============
+1.5.0     2016-12-13 `zip 1.5.0`_     `tar 1.5.0`_
+1.5.0     2016-12-13 `zip 1.5.0-rc1`_ `tar 1.5.0-rc1`_
+1.4.1     2016-11-01 `zip 1.4.1`_     `tar 1.4.1`_
+1.4.0     2016-10-31 `zip 1.4.0`_     `tar 1.4.0`_
+1.4.0-rc3 2016-09-14 `zip 1.4.0-rc3`_ `tar 1.4.0-rc3`_
+1.4.0-rc2 2016-08-29 `zip 1.4.0-rc2`_ `tar 1.4.0-rc2`_
+1.4.0-rc1 2016-05-26 `zip 1.4.0-rc1`_ `tar 1.4.0-rc1`_
 1.3.0     2015-05-27 `zip 1.3.0`_     `tar 1.3.0`_
 1.3.0-rc6 2015-04-27 `zip 1.3.0-rc6`_ `tar 1.3.0-rc6`_
 1.3.0-rc5 2015-04-27 `zip 1.3.0-rc5`_ `tar 1.3.0-rc5`_
@@ -52,6 +63,20 @@ Version   Date       Zip              Tar
 0.1       2012-03-27 `zip 0.1`_       `tar 0.1`_
 ========= ========== ================ ==============
 
+.. _zip 1.5.0: https://github.com/cyclus/cyclus/archive/1.5.0.zip
+.. _tar 1.5.0: https://github.com/cyclus/cyclus/archive/1.5.0.tar.gz
+.. _zip 1.5.0-rc1: https://github.com/cyclus/cyclus/archive/1.5.0-rc1.zip
+.. _tar 1.5.0-rc1: https://github.com/cyclus/cyclus/archive/1.5.0-rc1.tar.gz
+.. _zip 1.4.1: https://github.com/cyclus/cyclus/archive/1.4.1.zip
+.. _tar 1.4.1: https://github.com/cyclus/cyclus/archive/1.4.1.tar.gz
+.. _zip 1.4.0: https://github.com/cyclus/cyclus/archive/1.4.0.zip
+.. _tar 1.4.0: https://github.com/cyclus/cyclus/archive/1.4.0.tar.gz
+.. _zip 1.4.0-rc3: https://github.com/cyclus/cyclus/archive/1.4.0-rc3.zip
+.. _tar 1.4.0-rc3: https://github.com/cyclus/cyclus/archive/1.4.0-rc3.tar.gz
+.. _zip 1.4.0-rc2: https://github.com/cyclus/cyclus/archive/1.4.0-rc2.zip
+.. _tar 1.4.0-rc2: https://github.com/cyclus/cyclus/archive/1.4.0-rc2.tar.gz
+.. _zip 1.4.0-rc1: https://github.com/cyclus/cyclus/archive/1.4.0-rc1.zip
+.. _tar 1.4.0-rc1: https://github.com/cyclus/cyclus/archive/1.4.0-rc1.tar.gz
 .. _zip 1.3.0: https://github.com/cyclus/cyclus/archive/1.3.0.zip
 .. _tar 1.3.0: https://github.com/cyclus/cyclus/archive/1.3.0.tar.gz
 .. _zip 1.3.0-rc6: https://github.com/cyclus/cyclus/archive/1.3.0-rc6.zip

diff --git a/source/previous/v1.2.rst b/source/previous/v1.2.rst
@@ -28,10 +28,10 @@ Major features
 Since v1.1,
 
 * Cyclus: 95 commits resulted in 644 changed files encompassing a net 2347
-line insertions(+) and 397 deletions(-).
+  line insertions(+) and 397 deletions(-).
 
-* Cycamore: 33 commits resulted in 15 changed files encompassing a net 93
-line insertions(+) and 91 deletions(-).
+* Cycamore: 33 commits resulted in 15 changed files encompassing a net 93 line
+  insertions(+) and 91 deletions(-).
 
 Contributors
 ============