Proposed LSST DESC Notes LSSTDESC#284

doc/LSST_DESC_Notes/0001_twinkles_design/index.ipynb

@@ -0,0 +1,231 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<!-- ![](./_static/header.png) -->\n",
+    "<img src=\"./_static/header.png\",width=100%>\n",
+    "\n",
+    "LSST DESC Notes Template and Author Guidelines\n",
+    "==============================================\n",
+    "\n",
+    "*Heather Kelly (SLAC), Phil Marshall (SLAC)*\n",
+    "\n",
+    "LSST DESC Notes are designed to be citeable, and so need to conform to\n",
+    "the expectations of the academic research community to some extent. They\n",
+    "should contain a short abstract, which should be placed here. In this\n",
+    "Note we outline the steps for starting a new LSST DESC Note, getting it\n",
+    "reviewed within the collaboration, and then \"publishing\" it (not in a\n",
+    "journal, but on the web nonetheless). We then provide a quick\n",
+    "introduction to preparing Notes in restructuredtext, highlighting\n",
+    "aspects of LSST DESC Note style, and giving some pointers to good\n",
+    "resources.\n",
+    "\n",
+    "This Note was generated on: |date|"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Introduction\n",
+    "------------\n",
+    "\n",
+    "This is a template restructuredtext LSST DESC Note, for you to adapt for\n",
+    "your own work. It also contains instructions for how to get started\n",
+    "writing a note."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Getting Started\n",
+    "---------------\n",
+    "\n",
+    "-   Fork the GitHub repository of your project if you haven't already.\n",
+    "-   Under the doc/LSST\\_DESC\\_Notes directory (which you might have to\n",
+    "    create), make a new subdirectory with a suitable name to contain\n",
+    "    your LSST DESC Note. This name needs to be unique to this\n",
+    "    repository, but need not contain the name of the repository.\n",
+    "-   Copy the [Computing Infrastructure LSST DESC Note\n",
+    "    template](https://github.com/DarkEnergyScienceCollaboration/ComputingInfrastructure/blob/master/doc/LSST_DESC_Notes/template_LSST_DESC_Note.rst) (i.e.\n",
+    "    this file) into your new directory, and rename it `index.rst`.\n",
+    "-   Edit your new index.rst file with the contents of your Note,\n",
+    "    following the guidelines in the template.\n",
+    "-   Add files for figures in a subfolder called \\_static.\n",
+    "-   When your Note is complete and ready for review, submit a Pull\n",
+    "    Request to the base repo and ask your project's leads and/or your\n",
+    "    working group's conveners to review it.\n",
+    "-   The project leads will review your Note, iterate with you on\n",
+    "    modifications to it via the comments on the Pull Request, and\n",
+    "    finally merge it into the repository to signify that the Note\n",
+    "    is accepted. They will then tag the repo, to mark the first version\n",
+    "    of this LSST DESC Note."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Sectioning\n",
+    "----------\n",
+    "\n",
+    "As you can see above, your content can easily be divided into sections.\n",
+    "You can also make subsections, as follows.\n",
+    "\n",
+    "### A Subsection\n",
+    "\n",
+    "You can even have subsubsections, like this:\n",
+    "\n",
+    "#### A Subsubsection\n",
+    "\n",
+    "See? This is a subsubsection.\n",
+    "\n",
+    "#### Another Subsubsection\n",
+    "\n",
+    "And so is this.\n",
+    "\n",
+    "### Another Subsection\n",
+    "\n",
+    "And so on."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Math\n",
+    "----\n",
+    "\n",
+    "You can typeset mathematics using latex commands like this:\n",
+    "\n",
+    "$$\\langle f(k) \\rangle = \\frac{ \\sum_{t=0}^{N}f(t,k) }{N}$$\n",
+    "\n",
+    "While this does not render from `rst` on GitHub, it should get [picked up by\n",
+    "Sphinx](http://www.sphinx-doc.org/en/stable/ext/math.html) later and\n",
+    "will be available for you to re-use in future latex documents."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Code\n",
+    "----\n",
+    "\n",
+    "You can show code in blocks like this:\n",
+    "\n",
+    "```python\n",
+    "print \"Hello World\"\n",
+    "```\n",
+    "\n",
+    "or this:\n",
+    "\n",
+    "```bash\n",
+    "echo \"Hello World\"\n",
+    "```\n",
+    "\n",
+    "Inline mentions of code `objects` can be made using backquotes.\n",
+    "\n",
+    "You can also include live code blocks and their outputs, in the usual way. However, it is strongly recommended restart the kernel and clear all outputs before committing changes to the notebook, to prevent the Note's repo expanding to large size. A better approach is to finalize the graphical outputs of the notebook and then save them in the `_static` folder, before deisplaying them in a markdown cell using `![]()` formatting. This way you can keep the number of commits of large binary elements to a minimum.\n",
+    "\n",
+    "Here is some example code, that will run when this notebook is live:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Hello World\n"
+     ]
+    }
+   ],
+   "source": [
+    "print \"Hello World\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Figures\n",
+    "-------\n",
+    "\n",
+    "To add figures, add the required image file (PNG, SVG or JPG preferred)\n",
+    "to the `_static` subdirectory in your Note's folder. Here's an example:\n",
+    "\n",
+    "![](./_static/desc-logo.png)\n",
+    "This is the figure caption: above we have the LSST DESC logo, in PNG format.\n",
+    "\n",
+    "And then the text continues. Note that GitHub ignores the image sizing\n",
+    "commands when presenting reST format documents; sphinx might not."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "References\n",
+    "----------\n",
+    "\n",
+    "You can cite papers (or anything else) by providing hyperlinks. For\n",
+    "example, you might have been impressed by the DESC White Paper [(LSST\n",
+    "Dark Energy Science Collaboration\n",
+    "2012)](http://arxiv.org/abs/1211.0310). It should be possible to convert\n",
+    "these links to latex citations automatically later."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Further Resources\n",
+    "-----------------\n",
+    "\n",
+    "LSST DESC notes are styled after LSST technotes [(Sick\n",
+    "2016)](https://sqr-000.lsst.io/). You can also [view the restructured\n",
+    "text of (Sick\n",
+    "2016)](https://github.com/lsst-sqre/sqr-000/blob/master/index.rst).\n",
+    "Another nice example of an LSST technote is [(Wood-Vasey\n",
+    "2016)](http://dmtn-008.lsst.io/) - again, the restructured text is\n",
+    "visible\n",
+    "[here](https://github.com/lsst-dm/dmtn-008/blob/master/index.rst).\n",
+    "\n",
+    "For a guide to reStructuredText writing, please see the [LSST docs reST\n",
+    "styleguide](http://docs.lsst.codes/en/latest/development/docs/rst_styleguide.html).\n",
+    "There are many other reST resources on the web, such as [this\n",
+    "cheatsheet](https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst)."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 2",
+   "language": "python",
+   "name": "python2"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

doc/LSST_DESC_Notes/0001_twinkles_design/index.rst

@@ -0,0 +1,102 @@
+..
+  Template for LSST DESC Notes, including guidelines for authors.
+
+  Heather Kelly & Phil Marshall, Summer 2016
+
+  See also:
+  * https://github.com/lsst-sqre/sqr-000/blob/master/index.rst for an LSST technote deescribing LSST technotes, on which DESC notes are styled.
+  * https://github.com/lsst-dm/dmtn-008/blob/master/index.rst for a nice example LSST technote by Michael Wood-Vasey, which is rendered by the LSST technotes system at http://dmtn-008.lsst.io/en/latest/
+  * http://docs.lsst.codes/en/latest/development/docs/rst_styleguide.html for a guide to reStructuredText writing, and https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst for a nice cheatsheet.
+
+
+===============================================
+LSST DESC Notes: Template and Author Guidelines
+===============================================
+
+*Heather Kelly, Phil Marshall*
+
+.. |date| date::
+This Note was generated on: |date|
+
+
+Introduction
+============
+This is a template restructuredtext LSST DESC Note, for you to adapt for your own work. It also contains instructions for how to get started writing a note.
+
+Getting Started
+===============
+* Fork the GitHub repository of your project if you haven't already. 
+* Under the doc/LSST_DESC_Notes directory (which you might have to create), make a new subdirectory with a suitable name to contain your LSST DESC Note. This name needs to be unique to this repository, but need not contain the name of the repository.
+* Copy the `Computing Infrastructure LSST DESC Note template <https://github.com/DarkEnergyScienceCollaboration/ComputingInfrastructure/blob/master/doc/LSST_DESC_Notes/template_LSST_DESC_Note.rst>`_ (i.e. this file) into your new directory, and rename it ``index.rst``.
+* Edit your new `index.rst` file with the contents of your Note, following the guidelines in the template.
+* Add files for figures in a subfolder called `_static`.
+* When your Note is complete and ready for review, submit a Pull Request to the base repo and ask your project's leads and/or your working group's conveners to review it.
+* The project leads will review your Note, iterate with you on modifications to it via the comments on the Pull Request, and finally merge it into the repository to signify that the Note is accepted. They will then tag the repo, to mark the first version of this LSST DESC Note.
+
+Sectioning 
+==========
+As you can see above, your content can easily be divided into sections. You can also make subsections, as follows.
+
+A Subsection
+------------
+You can even have subsubsections, like this:
+
+A Subsubsection
+^^^^^^^^^^^^^^^
+See? This is a subsubsection.
+
+Another Subsubsection
+^^^^^^^^^^^^^^^^^^^^^
+And so is this.
+
+Another Subsection
+------------------
+And so on.
+
+Math
+====
+
+You can typeset mathematics using latex commands like this:
+
+.. math::
+
+  \langle f(k) \rangle = \frac{ \sum_{t=0}^{N}f(t,k) }{N}
+
+While this does not render on GitHub, it should get `picked up by Sphinx <http://www.sphinx-doc.org/en/stable/ext/math.html>`_ later and will be available for you to re-use in future latex documents.
+
+
+Code
+====
+You can show code in blocks like this:
+
+.. code-block:: python
+
+  print "Hello World"
+
+or this:
+
+.. code-block:: bash
+
+  echo "Hello World"
+
+Inline mentions of code ``objects`` can be made using pairs of backquotes.
+
+
+Figures
+=======
+To add figures, add the required image file (PNG, SVG or JPG preferred) to the ``_static`` subdirectory in your Note's folder. Here's an example:
+
+.. figure:: ./_static/desc-logo.png
+  :name: fig-logo
+  :target: ./_static/desc-logo.png
+  :width: 200px
+  :align: center
+
+  This is the figure caption: above we have the LSST DESC logo, in PNG format.
+
+And then the text continues. Note that GitHub ignores the image sizing commands when presenting reST format documents; sphinx might not.
+
+
+References
+==========
+You can cite papers (or anything else) by providing hyperlinks. For example, you might have been impressed by the DESC White Paper `(LSST Dark Energy Science Collaboration 2012) <http://arxiv.org/abs/1211.0310>`_.  It should be possible to convert these links to latex citations automatically later.