Improved documentation

docs/_templates/sidebarintro.html

@@ -0,0 +1,20 @@
+<h3>About Pint</h3>
+Units
+You are currently looking at the documentation of version {{ version }}.
+<h3>Other Formats</h3>
+<p>
+  You can download the documentation in other formats as well:
+</p>
+<ul>
+  <li><a href="https://media.readthedocs.org/pdf/pint/latest/pint.pdf">as PDF</a>
+  <li><a href="https://media.readthedocs.org/htmlzip/pint/latest/pint.zip">as ePub</a>
+  <li><a href="https://media.readthedocs.org/epub/pint/latest/pint.epub">as zipped HTML</a>
+</ul>
+<h3>Useful Links</h3>
+<ul>
+  <li><a href="https://pypi.python.org/pypi/Pint/">Pint @ PyPI</a></li>
+  <li><a href="https://github.com/hgrecco/lantz">Code in GitHub</a></li>
+  <li><a href="https://github.com/hgrecco/pint/issues">Issue Tracker</a></li>
+</ul>
+
+

docs/_templates/sidebarlogo.html

@@ -0,0 +1,4 @@
+<p><a href="{{ pathto(master_doc) }}">
+  <img src="{{ pathto('_images/logo-full.jpg', 1) }}" alt="Logo" style="width:80%;height:80%"/>
+</a></p>
+

docs/_themes/flask/layout.html

@@ -21,7 +21,7 @@
 {% endblock %}
 {%- block footer %}
   <div class="footer">
-    &copy; Copyright {{ copyright }}.
+    &copy; Copyright {{ copyright }}. Pint {{ version }}.
     Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
   </div>
   {% if pagename == 'index' %}

docs/conf.py

@@ -46,20 +46,15 @@ master_doc = 'index'
 project = 'pint'
 author = 'Hernan E. Grecco'
 
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+
 version = pkg_resources.get_distribution(project).version
 release = version
 this_year = datetime.date.today().year
 copyright = '%s, %s' % (this_year, author)
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '0.1'
-# The full version, including alpha/beta/rc tags.
-release = '0.1'
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #language = None
@@ -142,6 +137,11 @@ html_static_path = ['_static']
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
+html_sidebars = {
+    'index':    ['sidebarintro.html', 'sourcelink.html', 'searchbox.html'],
+    '**':       ['sidebarlogo.html', 'localtoc.html', 'relations.html',
+                 'sourcelink.html', 'searchbox.html']
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

docs/defining.rst

@@ -76,7 +76,7 @@ You can also add prefixes programmatically:
 
 .. doctest::
 
-   >>> ureg.define('myprefix- = 30 = my')
+   >>> ureg.define('myprefix- = 30 = my-')
 
 where the number indicates the multiplication factor.
 

docs/getting.rst

@@ -1,17 +1,17 @@
 .. _getting:
 
-Getting Pint
+Installation
 ============
 
-Pint has no dependencies except Python_ itself. In runs on Python 2.7+ and 3.0+.
+Pint has no dependencies except Python_ itself. In runs on Python 2.7 and 3.0+.
 
 You can install it using pip_::
 
-    $ sudo pip install pint
+    $ pip install pint
 
-or you can also install by downloading the source code in PyPi_ and then running::
+or using easy_install_::
 
-    $ python setup.py install
+    $ easy_install pint
 
 That's all! You can check that Pint is correctly installed by starting up python, and importing pint:
 
@@ -22,7 +22,30 @@ That's all! You can check that Pint is correctly installed by starting up python
    Continuum Analytics that includes many scientific packages.
 
 
+Getting the code
+----------------
+
+You can also get the code from PyPI_ or GitHub_. You can either clone the public repository::
+
+    $ git clone git://github.com/hgrecco/pint.git
+
+Download the tarball::
+
+    $ curl -OL https://github.com/hgrecco/pint/tarball/master
+
+Or, download the zipball::
+
+    $ curl -OL https://github.com/hgrecco/pint/zipball/master
+
+Once you have a copy of the source, you can embed it in your Python package, or install it into your site-packages easily::
+
+    $ python setup.py install
+
+
+
+.. _easy_install: http://pypi.python.org/pypi/setuptools
 .. _Python: http://www.python.org/
 .. _pip: http://www.pip-installer.org/
 .. _PyPI: https://pypi.python.org/pypi/Pint/
 .. _`Anaconda CE`: https://store.continuum.io/cshop/anaconda
+.. _GitHub: https://github.com/hgrecco/pint

docs/index.rst

@@ -7,7 +7,7 @@ Pint: a Python units library
    :alt: Pint: **physical quantities**
    :class: floatingflask
 
-Pint is Python module/package to define, operate and manipulate **physical quantities**: the product of a numerical value and a unit of measurement. It allows arithmetic operations between them and conversions from and to different units.
+Pint is Python package to define, operate and manipulate **physical quantities**: the product of a numerical value and a unit of measurement. It allows arithmetic operations between them and conversions from and to different units.
 
 It is distributed with a comprehensive list of physical units, prefixes and constants. Due to it's modular design, you can extend (or even rewrite!) the complete list without changing the source code.
 
@@ -29,19 +29,22 @@ Adding and changing units and their definitions does not involve changing the co
 **Advanced string formatting**: a quantity can be formatted into string using PEP 3101 syntax.
 Extended conversion flags are given to provide symbolic, latex and pretty formatting.
 
+**Free to choose the numerical type**: You can use any numerical type (`fraction`, `float`, `decimal`, `numpy.ndarray`, etc). NumPy is not required but supported.
+
+**NumPy integration**: When you choose to use a NumPy ndarray, its methods and ufuncs are supported including automatic conversion of units. For example `numpy.arccos(q)` will require a dimensionless `q` and the units of the output quantity will be radian.
+
+**Handle temperature**: conversion between units with different reference points, like positions on a map or absolute temperature scales.
+
 **Small codebase**: easy to maintain codebase with a flat hierarchy.
 
 **Dependency free**: it depends only on Python and it's standard library.
 
 **Python 2 and 3**: a single codebase that runs unchanged in Python 2.7+ and Python 3.0+.
 
-**NumPy support**: Pint understands NumPy ndarray methods and ufuncs.
-
-**Handle temperature conversion**: it can convert between units with different reference points, like positions on a map or absolute temperature scales.
 
 
-Where to start
+User Guide
---------------
+----------
 
 .. toctree::
     :maxdepth: 1
@@ -49,15 +52,25 @@ Where to start
     getting
     tutorial
     numpy
-    defining
     nonmult
     pitheorem
+    defining
+
+
+More information
+----------------
+
+.. toctree::
+    :maxdepth: 1
+
     contributing
     faq
 
 
+One last thing
+--------------
 
-.. note:: *A small technical note*
+.. epigraph::
 
  The MCO MIB has determined that the root cause for the loss of the MCO spacecraft was the failure to use metric     units in the coding of a ground software file, “Small Forces,” used in trajectory models. Specifically, thruster performance data in English units instead of metric units was used in the software application code titled SM_FORCES (small forces). The output from the SM_FORCES application code as required by a MSOP Project Software Interface Specification (SIS) was to be in metric units of Newtonseconds (N-s). Instead, the data was reported in English units of pound-seconds (lbf-s). The Angular Momentum Desaturation (AMD) file contained the output data from the SM_FORCES software. The SIS, which was not followed, defines both the format and units of the AMD file generated by ground-based computers. Subsequent processing of the data from AMD file by the navigation software algorithm therefore, underestimated the effect on the spacecraft trajectory by a factor of 4.45, which is the required conversion factor from force in pounds to Newtons. An erroneous trajectory was computed using this incorrect data.
 
@@ -65,12 +78,4 @@ Where to start
             `PDF <ftp://ftp.hq.nasa.gov/pub/pao/reports/1999/MCO_report.pdf>`_
 
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
-
 

docs/tutorial.rst

@@ -188,8 +188,8 @@ If you want to use abbreviated unit names, suffix the specification with `~`:
 The same is true for repr (`r`), latex (`l`) and pretty (`p`) specs.
 
 
-Using it in your projects
+Using Pint in your projects
--------------------------
+---------------------------
 
 If you use Pint in multiple modules within you Python package, you normally want to avoid creating multiple instances of the unit registry.
 The best way to do this is by instantiating the registry in a single place. For example,`you can add the following code to your package `__init__.py`::