more doc

2025-05-09 23:04:07 +00:00 · 2016-04-12 23:14:30 -04:00 · 2016-04-12 23:14:30 -04:00 · 60b21171a6
commit 60b21171a6
parent f6bd538689
8 changed files with 117 additions and 9 deletions
--- a/doc/html/genindex.html
+++ b/doc/html/genindex.html
@ -42,8 +42,33 @@
 <h1 id="index">Index</h1>

 <div class="genindex-jumpbox">
+ <a href="#B"><strong>B</strong></a>
 
 </div>
+<h2 id="B">B</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="types.html#_CPPv2N5boost9histogram9axis_typeE">boost::histogram::axis_type (C++ type)</a>
+  </dt>
+
+      
+  <dt><a href="types.html#_CPPv2N5boost9histogram9histogramE">boost::histogram::histogram (C++ class)</a>
+  </dt>
+
+  </dl></td>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="types.html#_CPPv2N5boost9histogram9histogram6fill_cEjPKd">boost::histogram::histogram::fill_c (C++ function)</a>
+  </dt>
+
+      
+  <dt><a href="types.html#_CPPv2N5boost9histogram9histogram9histogramERK9axis_typez">boost::histogram::histogram::histogram (C++ function)</a>
+  </dt>
+
+  </dl></td>
+</tr></table>
+


          </div>
--- a/doc/html/index.html
+++ b/doc/html/index.html
@ -64,7 +64,8 @@
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Types</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="types.html#c-interface">C++ interface</a></li>
+<li class="toctree-l2"><a class="reference internal" href="types.html#the-histogram-class">The Histogram Class</a></li>
+<li class="toctree-l2"><a class="reference internal" href="types.html#axis-types">Axis Types</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="functions.html">Functions</a></li>
--- a/doc/html/notes.html
+++ b/doc/html/notes.html
@ -78,7 +78,7 @@
 <p>The Python and C++ interface are indentical - except when they are not. The exceptions are minor and concern cases where a more elegant and pythonic way of implementing exists.</p>
 <ul class="simple">
 <li>getter/setter-like functions are wrapped as properties</li>
-<li><code class="xref cpp cpp-func docutils literal"><span class="pre">histogram::fill()</span></code> and <code class="xref cpp cpp-func docutils literal"><span class="pre">histogram::wfill()</span></code></li>
+<li>C++ functions <code class="xref cpp cpp-func docutils literal"><span class="pre">histogram::fill()</span></code> and <code class="xref cpp cpp-func docutils literal"><span class="pre">histogram::wfill()</span></code> are wrapped by the single Python function <code class="xref py py-func docutils literal"><span class="pre">histogram.fill()</span></code></li>
 </ul>
 </div>
 </div>
--- a/doc/html/objects.inv
+++ b/doc/html/objects.inv
@ -2,5 +2,8 @@
 # Project: histogram
 # Version: 1.0
 # The remainder of this file is compressed using zlib.
-xÚm<EFBFBD>MN1F÷>Å\ HlÙ!-”ªp<C2AA><70>¸™H™¸Êx½=ù<>I$vþ^ží$rN£%=Ì¬Éaw?È
-ïFžìðtx<îŸß>öpYœdCnnífû¥FÐèŒSø›d+¾ÑF½Òl¿Æ6ÌlŒƒ™™´S°ØSoPç„R-i3L¤þY|½íêAîy
Ë&bó#b{»a£µ¥fpÄØýCY;Æ|EXÑX+Ìæ¹FðxA<78>NöC7Zü5ÃŒÂË±cfYýÌç'¡xaòFØvteÙþ*	øví¯<C3AD>@‘b	"ÌÉž
+xΪ<EFBFBD>’QOΓ …ίω$>Χd&<26><>7³ΤΝLk3χήPJ[…θ²ωλm΅Π6<CEA0>L}βήΓwΟB.¥6ΥLY)ά „ΟLgζ<67>RHΪΩb‡EίΦ¦α7Ω&MOwΙ}>L®Γΰ:ΜΕ0ω7ΫPZ[Β±ΦΏσ
Υ_„JΖyF¬Ω	b<><>xpρGΊ/®¥-/τΟΐΩνϋι	?ϋpRcQQ.+¨M<C2A8>
+I`΄‚A΄ώp³{L¶ρΛΫψ|=§ƒθθ'ί‚<CEAF>
+&
+z¶0Η9εξUG?%<25>°ΡsFμόΩ{Κ(Ή¤zΑϋτeΡΩdΠΘβ‡ΰφω
7σΪp:΅‘†<E28098>°}άYΒ¤ϊί!
]Όƒ–%PΔ}Δ<>
+Ά#Ύ<05>–TQA–¦“:ς΅<07>bEκε<1D>ζΠw·<77>β<EFBFBD>Σ©ζsk―9ϊ8vΐ~¬~<%ψ‰ea}
--- a/doc/html/searchindex.js
+++ b/doc/html/searchindex.js
--- a/doc/html/types.html
+++ b/doc/html/types.html
@ -41,8 +41,46 @@
            
  <div class="section" id="types">
 <h1>Types<a class="headerlink" href="#types" title="Permalink to this headline">¶</a></h1>
+<p>The library consists of a single <code class="xref cpp cpp-class docutils literal"><span class="pre">histogram</span></code> and several axis types which are stored in a <code class="docutils literal"><span class="pre">boost::variant</span></code> called <code class="xref cpp cpp-type docutils literal"><span class="pre">axis_type</span></code>. The axis types are created and passed to the constructor of the histogram to define its binning scheme. All following types are embedded in the <code class="docutils literal"><span class="pre">boost::histogram</span></code> namespace, which is omitted for brevity.</p>
+<div class="section" id="the-histogram-class">
+<h2>The Histogram Class<a class="headerlink" href="#the-histogram-class" title="Permalink to this headline">¶</a></h2>
 <div class="section" id="c-interface">
-<h2>C++ interface<a class="headerlink" href="#c-interface" title="Permalink to this headline">¶</a></h2>
+<h3>C++ interface<a class="headerlink" href="#c-interface" title="Permalink to this headline">¶</a></h3>
+<dl class="class">
+<dt id="_CPPv2N5boost9histogram9histogramE">
+<span id="boost::histogram::histogram"></span><em class="property">class </em><code class="descclassname"></code><code class="descname">histogram</code> : <em class="property">public</em> basic_histogram<a class="headerlink" href="#_CPPv2N5boost9histogram9histogramE" title="Permalink to this definition">¶</a></dt>
+<dd><p>The class implements an n-dimensional histogram, managing counts in bins.</p>
+<p>It inherits from <code class="xref cpp cpp-class docutils literal"><span class="pre">basic_histogram</span></code>, which manages the stored axis instances and the conversion of an n-dimensional tuple or index into an internal linear offset that is used to address the bin count. How the bin count is stored is an encapsulated implementation detail.</p>
+</dd></dl>
+
+<dl class="function">
+<dt id="_CPPv2N5boost9histogram9histogram9histogramERK9axis_typez">
+<span id="boost::histogram::histogram::histogram__axis_typeCR.z"></span><code class="descclassname">histogram::</code><code class="descname">histogram</code><span class="sig-paren">(</span><em class="property">const</em> <a class="reference internal" href="#_CPPv2N5boost9histogram9axis_typeE" title="boost::histogram::axis_type">axis_type</a> &amp;<em>a0</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost9histogram9histogram9histogramERK9axis_typez" title="Permalink to this definition">¶</a></dt>
+<dd><p>Constructors for a variable number of axis types, each defining the binning scheme for its dimension. Up to <code class="xref cpp cpp-var docutils literal"><span class="pre">BOOST_HISTOGRAM_AXIS_LIMIT</span></code> axis types can be passed to the constructor, yielding the same number of dimensions.</p>
+</dd></dl>
+
+<dl class="function">
+<dt id="_CPPv2N5boost9histogram9histogram6fill_cEjPKd">
+<span id="boost::histogram::histogram::fill_c__unsigned.doubleCP"></span><code class="descclassname">histogram::</code><code class="descname">fill_c</code><span class="sig-paren">(</span>unsigned <em>n</em>, <em class="property">const</em> double *<em>v</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost9histogram9histogram6fill_cEjPKd" title="Permalink to this definition">¶</a></dt>
+<dd><p>Fills the histogram with a c-array <code class="docutils literal"><span class="pre">v</span></code> of length <code class="docutils literal"><span class="pre">n</span></code>. A checks at run-time asserts that <code class="docutils literal"><span class="pre">n</span></code> agrees with the dimensions of the histogram.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="axis-types">
+<h2>Axis Types<a class="headerlink" href="#axis-types" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="id1">
+<h3>C++ interface<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<dl class="type">
+<dt id="_CPPv2N5boost9histogram9axis_typeE">
+<span id="boost::histogram::axis_type"></span><em class="property">type </em>boost::variant&lt;regular_axis, polar_axis, variable_axis, category_axis, integer_axis&gt; <code class="descclassname"></code><code class="descname">axis_type</code><a class="headerlink" href="#_CPPv2N5boost9histogram9axis_typeE" title="Permalink to this definition">¶</a></dt>
+<dd><p>A variant template which stores one of several axis objects.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="python-interface">
+<h3>Python interface<a class="headerlink" href="#python-interface" title="Permalink to this headline">¶</a></h3>
+</div>
 </div>
 </div>

@ -73,7 +111,8 @@
 <li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
 <li class="toctree-l1"><a class="reference internal" href="notes.html">Notes</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Types</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="#c-interface">C++ interface</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#the-histogram-class">The Histogram Class</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#axis-types">Axis Types</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="functions.html">Functions</a></li>
--- a/doc/sphinx/notes.rst
+++ b/doc/sphinx/notes.rst
@ -42,4 +42,4 @@ Congruence of C++ and Python interface
 The Python and C++ interface are indentical - except when they are not. The exceptions are minor and concern cases where a more elegant and pythonic way of implementing exists.

 * getter/setter-like functions are wrapped as properties
-* :cpp:func:`histogram::fill` and :cpp:func:`histogram::wfill`
+* C++ functions :cpp:func:`histogram::fill` and :cpp:func:`histogram::wfill` are wrapped by the single Python function :py:func:`histogram.fill`
--- a/doc/sphinx/types.rst
+++ b/doc/sphinx/types.rst
@ -1,8 +1,48 @@
 Types
 =====

+The library consists of a single :cpp:class:`histogram` and several axis types which are stored in a ``boost::variant`` called :cpp:type:`axis_type`. The axis types are created and passed to the constructor of the histogram to define its binning scheme. All following types are embedded in the ``boost::histogram`` namespace, which is omitted for brevity.
+
+The Histogram Class
+-------------------
+
 C++ interface
-------------
+^^^^^^^^^^^^^

+.. cpp:namespace:: boost::histogram

+.. cpp:class:: histogram : public basic_histogram

+    The class implements an n-dimensional histogram, managing counts in bins.
+
+    It inherits from :cpp:class:`basic_histogram`, which manages the stored axis instances and the conversion of an n-dimensional tuple or index into an internal linear offset that is used to address the bin count. How the bin count is stored is an encapsulated implementation detail.
+
+.. cpp:function:: histogram::histogram(const axis_type& a0, ...)
+
+    Constructors for a variable number of axis types, each defining the binning scheme for its dimension. Up to :cpp:var:`BOOST_HISTOGRAM_AXIS_LIMIT` axis types can be passed to the constructor, yielding the same number of dimensions.
+
+.. cpp:function:: histogram::fill_c(unsigned n, const double* v)
+
+    Fills the histogram with a c-array ``v`` of length ``n``. A checks at run-time asserts that ``n`` agrees with the dimensions of the histogram. Up to :cpp:var:`BOOST_HISTOGRAM_AXIS_LIMIT` dimensions are supported.
+
+.. cpp:function:: histogram::fill(double x0, ...)
+
+    Same as :cpp:func:`histogram::fill_c`, but passing the values directly.  Up to :cpp:var:`BOOST_HISTOGRAM_AXIS_LIMIT` dimensions are supported.
+
+.. cpp:function:: histogram::wfill_c(unsigned n, const double* v, double w)
+
+    Fills the histogram with a c-array ``v`` of length ``n``, using weight ``w``. A checks at run-time asserts that ``n`` agrees with the dimensions of the histogram. Up to :cpp:var:`BOOST_HISTOGRAM_AXIS_LIMIT` dimensions are supported.
+
+Axis Types
+----------
+
+C++ interface
+^^^^^^^^^^^^^
+
+.. cpp:type:: boost::variant\<regular_axis, polar_axis, variable_axis, \
+                              category_axis, integer_axis> axis_type
+
+    A variant template which stores one of several axis objects.
+
+Python interface
+^^^^^^^^^^^^^^^^