.. Automatically generated Sphinx-extended reStructuredText file from DocOnce source
   (https://github.com/hplgit/doconce/)

.. Document title:

Demo of admonition styles in DocOnce
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

:Authors: H. P. Langtangen
:Date: Oct 5, 2015

*Summary.* This note demonstrates how admonitions look like in the output format
**sphinx**.

The four main types of admonitions
==================================

Here is the warning admon:


.. admonition:: Division by zero is illegal

   Most math systems will give fatal errors if you divide by zero.
   
   .. code-block:: text
   
           Terminal> python -c 'print 4/0'
           Traceback (most recent call last):
             File "<string>", line 1, in <module>
           ZeroDivisionError: integer division or modulo by zero
   
   You should therefore be very careful with all expressions that may result
   in division by zero. In Python, you can use a ``try-except`` clause to
   test if some expression gives a ``ZeroDivisionError`` exception and take
   appropriate actions. One example of a numerical method where division
   by zero can cause problems is Newton's methods of finding solutions to
   algebraic equations :math:`f(x)=0`. In that algorithm, there is a division
   by :math:`f'(x)`.




Question admon (without title).


.. admonition:: Question

   What are the admon options for ``doconce format html``?
   
   .. Answer: ``--html_admon=``, ``--html_admon_shadow``, ``--html_admon_bg_color=``,
   
   .. ``--html_admon_bd_color``. There is also ``--html_box_shadow`` for boxes.




Summary admon:


.. admonition:: Summary

   The most popular methods for solving algebraic equations
   
   .. math::
            f(x) = 0 
   
   are
   
    * Newton's method
   
    * The Bisection method
   
    * The Secant method
   
    * The Fixed-Point method (:math:`f(x) = x - g(x)`)
   
   Of these, Newton's method is fastest, the Bisection method is the most
   reliable, the Secant method is a simplified Newton method, and the
   Fixed-Point method is obviously very problem dependent in its behavior
   since the user has the define the :math:`g` function.




Here is a *notice admon*:


.. admonition:: Tip: follow well-established conventions for variable names

   For example, in Python, variable and function names use
   lower case letters separated by underscore, as in
   ``vibration_with_damping`` (while Java typically would
   have ``vibrationWithDamping``). Class names apply cap words,
   as in ``ProblemClass``.




The four main admons are warning, notice, question, and summary.

The block, quote and plain box environment
==========================================

DocOnce features a ``block`` environment with or without title.


.. admonition:: Notice

   Blocks are often used in slides to frame a collection of things.





.. admonition:: Block with title

   Blocks can contain text, math, code, figures, movies.




Here is a quote environment (``quote``):


..

    Sayre's law states that
    "in any dispute the intensity of feeling is inversely
    proportional to the value of the issues at stake." 
    
    | By way of corollary, it adds: 
    | "That is why academic politics are so bitter." 
    | *Source*: `wikipedia <http://en.wikipedia.org/wiki/Sayre's_law>`__



Boxes are very simple frames (without any icons, background color,
or stash, except for a shadow)
used for important results like
(note: box frame is not available in format **sphinx**)


.. The below box could be typeset as .. admonition: Attention
   but we have decided not to do so since the admon needs a title
   (the box formatting is therefore just ignored)

The world most famous equation:

.. math::
         E = mc^2