Skip to content

Commit 2d3a388

Browse files
ddaleddale
committed
Update/simplify documentation
cleanup umath
1 parent d06cd26 commit 2d3a388

File tree

16 files changed

+45
-143
lines changed

16 files changed

+45
-143
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
*.pyc
2+
quantities.egg-info
3+
build

‎doc/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@
9393
# A list of ignored prefixes for module index sorting.
9494
#modindex_common_prefix = []
9595

96-
autosummary_generate = ['reference/intro.rst']
96+
#autosummary_generate = ['reference/intro.rst']
9797

9898
# -- Options for HTML output ---------------------------------------------------
9999

‎doc/devel/documenting.rst‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,10 @@ Organization of Quantities' documentation
3737
==========================================
3838

3939
The actual ReStructured Text files are kept in :file:`doc`. The main
40-
entry point is :file:`doc/index.rst`, which pulls in the
41-
:file:`index.rst` file for the user guide, developers guide, api reference,
42-
and the glossary. The documentation suite is built as a single document in
43-
order to make the most effective use of cross referencing, we want to make
40+
entry point is :file:`doc/index.rst`, which pulls in the
41+
:file:`index.rst` file for the user guide and the developers guide.
42+
The documentation suite is built as a single document in order to
43+
make the most effective use of cross referencing, we want to make
4444
navigating the Quantities documentation as easy as possible.
4545

4646
Additional files can be added to the various guides by including their base
@@ -170,9 +170,6 @@ mind:
170170
A bit about :ref:`referring-to-quantities-docs`:
171171
One more
172172

173-
* Please keep the :ref:`glossary` in mind when writing documentation. You can
174-
create a references to a term in the glossary with the ``:term:`` role.
175-
176173
* The autodoc extension will handle index entries for the API, but additional
177174
entries in the index_ need to be explicitly added.
178175

‎doc/devel/release.rst‎

Lines changed: 1 addition & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,6 @@
22
Releases
33
********
44

5-
Before creating a release, the version number needs to be updated in
6-
`quantities/__init__.py`. Then Quantities needs to be installed either with::
7-
8-
python setup.py install
9-
10-
or::
11-
12-
python setup.py develop
13-
14-
in order proceed with building the release, so the package version numbers will
15-
be advertised correctly for the installers and the documentation.
16-
17-
185
Creating Source Releases
196
========================
207

@@ -47,7 +34,7 @@ windows installer, open a DOS window, cd into the quantities source directory
4734
and run::
4835

4936
python setup.py build
50-
python setup.py bdist_wininst
37+
python setup.py bdist_msi
5138

5239
This creates the executable windows installer in the `dist/` directory.
5340

‎doc/glossary.rst‎

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎doc/index.rst‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,5 +26,3 @@ production use.
2626

2727
user/index.rst
2828
devel/index.rst
29-
reference/index.rst
30-
glossary.rst

‎doc/reference/index.rst‎

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎doc/reference/intro.rst‎

Lines changed: 0 additions & 17 deletions
This file was deleted.

‎doc/user/issues.rst‎

Lines changed: 0 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -13,27 +13,6 @@ operations are not yet fully functioning.
1313
>>> import quantities as pq
1414

1515

16-
Addition and subtraction
17-
========================
18-
19-
The addition (or subtraction) of quantities with different (but compatible)
20-
units raises an error.
21-
22-
>>> a = 1 * pq.m
23-
>>> b = 100 * pq.cm
24-
>>> a + b
25-
Traceback (most recent call last):
26-
...
27-
ValueError: can not add units of m and cm
28-
29-
You can get around this error by making sure all quantities have the same
30-
units.
31-
32-
>>> b.units = pq.m
33-
>>> print a + b
34-
2.0 m
35-
36-
3716
Temperature conversion
3817
======================
3918

‎quantities/__init__.py‎

Lines changed: 23 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,40 @@
11
"""
2-
3-
This is a crash-course introduction to the Quantities package.
4-
Quantities attempts to handle operations involving values that have
5-
both magnitude and dimensionality, the latter being described by a
6-
system of units, and possibly an uncertainty.
2+
Quantities is designed to handle arithmetic and conversions of
3+
physical quantities, which have a magnitude, dimensionality specified
4+
by various units, and possibly an uncertainty. Quantities is designed
5+
to work with numpy's standard ufuncs, many of which are already
6+
supported. The package is actively developed, and while the current
7+
features and API are stable, test coverage is incomplete and so the
8+
package is not suggested for production use.
79
810
It is strongly suggested to import quantities to its own namespace, so
911
units and constants variables are not accidentally overwritten::
1012
1113
>>> import quantities as pq
1214
13-
Here pq stands for "physical quantities" or "python quantities". There
14-
are a number of ways to create a quantity. The Quantity constructor
15-
can be used similar to numpy.array, by passing a sequence. Units can
16-
be designated using a string containing standard unit abbreviations or
17-
unit names. For example::
18-
19-
>>> q = pq.Quantity([1,2,3], 'J')
20-
>>> q = pq.Quantity([1,2,3], 'joules')
21-
22-
Units are also available as variables, and can be passed to Quantity::
23-
24-
>>> q = pq.Quantity([1,2,3], pq.J)
25-
26-
In practice though, it is usually more convenient to think of
27-
quantities as a combination of a magnitude and units. These two
28-
quantities are equivalent::
15+
Here pq stands for "physical quantities" or "python quantities".
16+
There are a number of ways to create a quantity. In practice, it is
17+
convenient to think of quantities as a combination of a magnitude and
18+
units. These two quantities are equivalent::
2919
3020
>>> import numpy as np
3121
>>> q = np.array([1,2,3]) * pq.J
3222
>>> q = [1,2,3] * pq.J
3323
>>> print q
3424
[ 1. 2. 3.] J
3525
26+
The Quantity constructor can also be used to create quantities,
27+
similar to numpy.array. Units can be designated using a string
28+
containing standard unit abbreviations or unit names. For example::
29+
30+
>>> q = pq.Quantity([1,2,3], 'J')
31+
>>> q = pq.Quantity([1,2,3], 'joules')
32+
33+
Units are also available as variables, and can be passed to
34+
Quantity::
35+
36+
>>> q = pq.Quantity([1,2,3], pq.J)
37+
3638
You can modify a quantity's units in place::
3739
3840
>>> q = 1 * pq.m

0 commit comments

Comments
 (0)