Skip to content

Commit f122f67

Browse files
carandraugcarandraug
committed
doc: add install instructions and INSTALL file
1 parent fa0d0ad commit f122f67

File tree

5 files changed

+215
-1
lines changed

5 files changed

+215
-1
lines changed

‎INSTALL‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
Microscope is available on the Python Package Index (PyPI) and can be
2+
`installed like any other Python package
3+
<https://packaging.python.org/tutorials/installing-packages/>`_. The
4+
short version of it is use pip::
5+
6+
pip install microscope
7+
8+
Note that you need to have Python and pip already installed on your
9+
system.
10+
11+
12+
Requirements
13+
============
14+
15+
Microscope can run in any operating system with Python installed but
16+
individual devices and intended usage may add specific requirements:
17+
18+
- **hardware performance**: control of devices at high speed, namely
19+
image acquisition at very high rates, may require a fast connection
20+
to the camera, high amount of memory, or a disk with fast write
21+
speeds. In such case, it may be advantageous to have a dedicated
22+
machine for the camera.
23+
24+
- **external libraries**: control of many devices is performed via
25+
vendor provided external libraries which are often limited to
26+
specific operating systems. For example, Alpao does not provide a
27+
library for Linux systems so control of Alpao deformable mirrors is
28+
limited to Windows. See the :ref:`Dependencies
29+
<install-dependencies>` sections below.
30+
31+
If there are multiple devices with high resources or incompatible
32+
requirements they can be distributed over multiple computers. For
33+
example, two cameras acquiring images at a high frame rate or a camera
34+
that requires Windows paired with a deformable mirror that requires
35+
Linux. See the :ref:`Examples <examples>` section.
36+
37+
38+
.. _install-dependencies:
39+
40+
Dependencies
41+
============
42+
43+
Microscope has very few dependencies. All are Python packages
44+
available on PyPI and will be automatically resolved if Microscope is
45+
installed with pip. However, the interface to many devices is done
46+
via an external library (or SDK, or driver) that is only provided by
47+
the device vendor.
48+
49+
To identify if an external library is required, check the associated
50+
module documentation. If an external library is required, contact the
51+
device vendor for install instructions. Cameras, deformable mirrors,
52+
and spatial light modulators all require an external library. Filter
53+
wheels, lasers, and stages typically do not but there are exceptions.
54+
55+
56+
Development sources
57+
===================
58+
59+
Microscope development sources are available on github. To install
60+
the current development version of Microscope::
61+
62+
git clone https://github.com/MicronOxford/microscope.git pip
63+
pip install --no-index microscope/
64+
65+
Also consider using editable mode if you plan to make changes to the
66+
project::
67+
68+
pip install --no-index --editable microscope/
69+
70+
Multiple Microscope versions
71+
----------------------------
72+
73+
Python package system will not by default handle multiple versions of
74+
a package. If installing from development, beware to not overwrite a
75+
previous installation. A typical approach to address this issue is to
76+
use `virtual environments
77+
<https://packaging.python.org/tutorials/installing-packages/#creating-and-using-virtual-environments>`_.
78+
79+
Un-merged features
80+
------------------
81+
82+
Many features are still in development and have not been merged in the
83+
master branch. To try such features, you will need to know the branch
84+
name and the repository where such feature is being developed. For
85+
example, to try Toshiki Kubo's implementation of the Mirao52e
86+
deformable mirror::
87+
88+
git remote add toshiki https://github.com/toshikikubo/microscope.git
89+
git fetch toshiki
90+
git checkout toshiki/mirao52e
91+
pip install --no-index ./

‎doc/examples.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
no Back-Cover Texts. A copy of the license is included in the
99
section entitled "GNU Free Documentation License".
1010
11+
.. _examples:
12+
1113
Examples
1214
********
1315

‎doc/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,9 @@ Python Microscope
1919
examples
2020
supported-devices
2121
API <api/modules>
22+
installing
2223
hacking
23-
maintainer
24+
maintaining
2425
history
2526
contributors
2627

‎doc/installing.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
.. Copyright (C) 2019 David Miguel Susano Pinto <david.pinto@bioch.ox.ac.uk>
2+
3+
Permission is granted to copy, distribute and/or modify this
4+
document under the terms of the GNU Free Documentation License,
5+
Version 1.3 or any later version published by the Free Software
6+
Foundation; with no Invariant Sections, no Front-Cover Texts, and
7+
no Back-Cover Texts. A copy of the license is included in the
8+
section entitled "GNU Free Documentation License".
9+
10+
Installing
11+
**********
12+
13+
.. include:: ../INSTALL

‎doc/maintaining.rst‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
.. Copyright (C) 2019 David Miguel Susano Pinto <david.pinto@bioch.ox.ac.uk>
2+
3+
Permission is granted to copy, distribute and/or modify this
4+
document under the terms of the GNU Free Documentation License,
5+
Version 1.3 or any later version published by the Free Software
6+
Foundation; with no Invariant Sections, no Front-Cover Texts, and
7+
no Back-Cover Texts. A copy of the license is included in the
8+
section entitled "GNU Free Documentation License".
9+
10+
Maintaining
11+
***********
12+
13+
This document includes information for those deeper in the project.
14+
15+
16+
The NEWS file
17+
=============
18+
19+
The file should only include user visible changes worth mentioning.
20+
For example, adding support for a new device should be listed but
21+
removing multiple lines to address code duplication should not.
22+
23+
It's easier to keep the NEWS file up to date as changes are made.
24+
This prevents having to check all the changes since the last release
25+
for such relevant changes. Ideally, the same commit that makes the
26+
relevant change should also add the entry to the NEWS file.
27+
28+
29+
Steps to make a release
30+
=======================
31+
32+
Because the NEWS file is supposed to always be kept up to date, there
33+
should be no need to check it.
34+
35+
#. Change version number on `setup.py` and date on `NEWS`. Commit
36+
these changes only. Note that we use `release-N` for tag and not
37+
`v.N`. This will enable us to one day perform snapshot releases
38+
with tags such as `snapshot-N`::
39+
40+
VERSION=$(python setup.py --version)
41+
COMMIT=$(git rev-parse HEAD | cut -c1-12)
42+
sed -i "s,yyyy/mm/dd,$(date +%Y/%m/%d)," NEWS
43+
git commit -m "maint: release $VERSION" setup.py NEWS
44+
git tag -s -u $GPGKEY \
45+
-m "Added tag release-$VERSION for commit $COMMIT" release-$VERSION
46+
47+
#. Build a source distribution from a git archive export. Performing
48+
a release from a git archive will ensure that the release will not
49+
accidentally include modified or untracked files::
50+
51+
rm -rf target/
52+
git archive --format=tar --prefix="target/" HEAD | tar -x
53+
cd target/
54+
python setup.py sdist --formats=gztar
55+
56+
We should probably do this from a git clone and not an archive to
57+
ensure that we are not using a commit that has not been pushed yet.
58+
59+
#. Upload and sign distribution::
60+
61+
twine upload -r pypi -s -i $GPGKEY target/dist/microscope-X.tar.gz
62+
63+
#. Add `+dev` to version string and a new entry on the NEWS file::
64+
65+
sed -i "s,\(^project_version = '[^+]*\)',\1+dev'," setup.py
66+
# manually add new version line on NEWS file
67+
git commit setup.py NEWS \
68+
-m "maint: set version to $VERSION+dev after $VERSION release."
69+
git push upstream master
70+
git push upstream release-$VERSION
71+
72+
73+
Documentation
74+
=============
75+
76+
The documentation is generated automatically with `sphinx
77+
<https://www.sphinx-doc.org/en/master/>`_. The API section is
78+
generated from the inline docstrings and makes use of `Sphinx's
79+
Napoleon extension
80+
<http://www.sphinx-doc.org/en/stable/ext/napoleon.html>`_. It is
81+
generated with::
82+
83+
python setup.py build_sphinx
84+
85+
Versioning
86+
==========
87+
88+
We use the style `major.minor.patch` for releases and haven't yet had
89+
to deal with rc.
90+
91+
In between releases and snapshots, we use the `dev` as a local version
92+
identifiers as per `PEP 440
93+
<https://www.python.org/dev/peps/pep-0440/>`_ so a version string
94+
`0.0.1+dev` is the release `0.0.1` plus development changes on top of
95+
it (and not development release for an upcoming `0.0.1`). With
96+
examples:
97+
98+
* `0.0.1` - major version 0, minor version 0, patch version 1
99+
100+
* `0.0.1+dev` - not a public release. A development build, probably
101+
from VCS sources, sometime *after* release `0.0.1`. Note the use of
102+
`+` which marks `dev` as a local version identifier.
103+
104+
* `0.0.1.dev1` - we do not do this. PEP 440 states this would be the
105+
first development public release *before* `0.0.1`. We use `+dev`
106+
which are local version and not public releases. This is only
107+
mentioned here to avoid confusion for people used to that style.

0 commit comments

Comments
 (0)