Update index.rst

This commit is contained in:
tpollina 2019-12-01 18:52:51 -08:00 committed by GitHub
parent 63f1397807
commit e0d3ea7275
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -1,159 +1,195 @@
An h1 header
.. _install:
============
Installation
============
Paragraphs are separated by a blank line.
2nd paragraph. *Italic*, **bold**, and `monospace`. Itemized lists
look like:
* this one
* that one
* the other one
Note that --- not considering the asterisk --- the actual text
content starts at 4-columns in.
> Block quotes are
> written like so.
>
> They can span multiple paragraphs,
> if you like.
Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all
in chapters 12--14"). Three dots ... will be converted to an ellipsis.
Unicode is supported. ☺
.. currentmodule:: picamera
.. _raspbian_install:
An h2 header
------------
Raspbian installation
=====================
Here's a numbered list:
If you are using the `Raspbian`_ distro, it is best to install picamera using
the system's package manager: apt. This will ensure that picamera is easy to
keep up to date, and easy to remove should you wish to do so. It will also make
picamera available for all users on the system. To install picamera using apt
simply::
1. first item
2. second item
3. third item
$ sudo apt-get update
$ sudo apt-get install python-picamera python3-picamera
Note again how the actual text starts at 4 columns in (4 characters
from the left side). Here's a code sample:
To upgrade your installation when new releases are made you can simply use
apt's normal upgrade procedure::
# Let me re-iterate ...
for i in 1 .. 10 { do-something(i) }
$ sudo apt-get update
$ sudo apt-get upgrade
As you probably guessed, indented 4 spaces. By the way, instead of
indenting the block, you can use delimited blocks, if you like:
If you ever need to remove your installation::
~~~
define foobar() {
print "Welcome to flavor country!";
}
~~~
$ sudo apt-get remove python-picamera python3-picamera
(which makes copying & pasting easier). You can optionally mark the
delimited block for Pandoc to syntax highlight it:
.. note::
~~~python
import time
# Quick, count to ten!
for i in range(10):
# (but not *too* quick)
time.sleep(0.5)
print(i)
~~~
If you are using a recent installation of Raspbian, you may find that the
python-picamera package is already installed (it is included by default
in recent versions).
.. _Raspbian: http://www.raspbian.org/
.. _non_raspbian_install:
### An h3 header ###
Alternate distro installation
=============================
Now a nested list:
On distributions other than Raspbian, it is probably simplest to install system
wide using Python's ``pip`` tool::
1. First, get these ingredients:
$ sudo pip install picamera
* carrots
* celery
* lentils
If you wish to use the classes in the :mod:`picamera.array` module then specify
the "array" option which will pull in numpy as a dependency (be warned that
building numpy takes a *long* time on a Pi)::
2. Boil some water.
$ sudo pip install "picamera[array]"
3. Dump everything in the pot and follow
this algorithm:
To upgrade your installation when new releases are made::
find wooden spoon
uncover pot
stir
cover pot
balance wooden spoon precariously on pot handle
wait 10 minutes
goto first step (or shut off burner when done)
$ sudo pip install -U picamera
Do not bump wooden spoon or it will fall.
If you ever need to remove your installation::
Notice again how text always lines up on 4-space indents (including
that last line which continues item 3 above).
$ sudo pip uninstall picamera
Here's a link to [a website](http://foo.bar), to a [local
doc](local-doc.html), and to a [section heading in the current
doc](#an-h2-header). Here's a footnote [^1].
[^1]: Some footnote text.
.. _firmware:
Tables can look like this:
Firmware upgrades
=================
Name Size Material Color
------------- ----- ------------ ------------
All Business 9 leather brown
Roundabout 10 hemp canvas natural
Cinderella 11 glass transparent
The behaviour of the Pi's camera module is dictated by the Pi's firmware. Over
time, considerable work has gone into fixing bugs and extending the
functionality of the Pi's camera module through new firmware releases. Whilst
the picamera library attempts to maintain backward compatibility with older Pi
firmwares, it is only tested against the latest firmware at the time of
release, and not all functionality may be available if you are running an older
firmware. As an example, the :attr:`~PiCamera.annotate_text` attribute relies
on a recent firmware; older firmwares lacked the functionality.
Table: Shoes sizes, materials, and colors.
You can determine the revision of your current firmware with the following
command::
(The above is the caption for the table.) Pandoc also supports
multi-line tables:
$ uname -a
-------- -----------------------
Keyword Text
-------- -----------------------
red Sunsets, apples, and
other red or reddish
things.
The firmware revision is the number after the ``#``::
green Leaves, grass, frogs
and other things it's
not easy being.
-------- -----------------------
Linux kermit 3.12.26+ #707 PREEMPT Sat Aug 30 17:39:19 BST 2014 armv6l GNU/Linux
/
/
firmware revision --+
A horizontal rule follows.
On Raspbian, the standard upgrade procedure should keep your firmware
up to date::
***
$ sudo apt-get update
$ sudo apt-get upgrade
Here's a definition list:
.. warning::
apples
: Good for making applesauce.
Previously, these documents have suggested using the ``rpi-update`` utility
to update the Pi's firmware; this is now discouraged. If you have
previously used the ``rpi-update`` utility to update your firmware, you can
switch back to using ``apt`` to manage it with the following commands::
oranges
: Citrus!
$ sudo apt-get update
$ sudo apt-get install --reinstall libraspberrypi0 libraspberrypi-{bin,dev,doc} raspberrypi-bootloader
$ sudo rm /boot/.firmware_revision
tomatoes
: There's no "e" in tomatoe.
You will need to reboot after doing so.
Again, text is indented 4 spaces. (Put a blank line between each
term and its definition to spread things out more.)
.. note::
Here's a "line block" (note how whitespace is honored):
Please note that the `PiTFT`_ screen (and similar GPIO-driven screens)
requires a custom firmware for operation. This firmware lags behind the
official firmware and at the time of writing lacks several features
including long exposures and text overlays.
| Line one
| Line too
| Line tree
.. _PiTFT: http://www.adafruit.com/product/1601
and images can be specified like so:
![example image](example-image.jpg "An exemplary image")
.. _dev_install:
Inline math equation: $\omega = d\phi / dt$. Display
math should get its own line like so:
Development installation
========================
$$I = \int \rho R^{2} dV$$
If you wish to develop picamera itself, it is easiest to obtain the source by
cloning the GitHub repository and then use the “develop” target of the Makefile
which will install the package as a link to the cloned repository allowing
in-place development (it also builds a tags file for use with vim/emacs with
Exuberants ctags utility). The following example demonstrates this method
within a virtual Python environment::
$ sudo apt-get install lsb-release build-essential git git-core \
exuberant-ctags python-virtualenv python3-virtualenv python-dev \
python3-dev libjpeg8-dev zlib1g-dev libav-tools \
texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
$ virtualenv -p /usr/bin/python3 sandbox
$ source sandbox/bin/activate
(sandbox) $ git clone https://github.com/waveform80/picamera.git
(sandbox) $ cd picamera
(sandbox) $ make develop
To pull the latest changes from git into your clone and update your
installation::
$ source sandbox/bin/activate
(sandbox) $ cd picamera
(sandbox) $ git pull
(sandbox) $ make develop
To remove your installation blow away the sandbox and the clone::
$ rm -fr ~/sandbox/ ~/picamera/
For anybody wishing to hack on the project, I would strongly recommend reading
through the :class:`PiCamera` class' source, to get a handle on using the
``mmalobj`` layer. This is a layer introduced in picamera 1.11 to ease the
usage of ``libmmal`` (the underlying library that picamera, ``raspistill``,
and ``raspivid`` all rely upon).
Beneath ``mmalobj`` is a :mod:`ctypes` translation of the ``libmmal`` headers
but my hope is that most developers will never need to deal with this
directly (thus, a working knowledge of C is hopefully no longer necessary to
hack on picamera).
Various classes for specialized applications also exist
(:class:`PiCameraCircularIO`, :class:`~array.PiBayerArray`, etc.)
Even if you dont feel up to hacking on the code, Id love to hear suggestions
from people of what youd like the API to look like (even if the code itself
isnt particularly pythonic, the interface should be)!
.. _test_suite:
Test suite
==========
If you wish to run the picamera test suite, follow the instructions in
:ref:`dev_install` above and then make the "test" target within the sandbox::
$ source sandbox/bin/activate
(sandbox) $ cd picamera
(sandbox) $ make test
.. warning::
The test suite takes a *very* long time to execute (at least 1 hour on an
overclocked Pi 3). Depending on configuration, it can also lockup the
camera requiring a reboot to reset, so ensure you are familiar with SSH or
using alternate TTYs to access a command line in the event you need to
reboot.
And note that you can backslash-escape any punctuation characters
which you wish to be displayed literally, ex.: \`foo\`, \*bar\*, etc.