doc changes, now track api!

For some reason I wasn't tracking the api docs in git

.gitignore

@@ -17,7 +17,7 @@ htmlcov
 MANIFEST
 
 # Sphinx
-docs/api
+#docs/api
 docs/_build
 
 # Eclipse editor project files

docs/api/api.rst

@@ -0,0 +1,23 @@
+.. Installation guide, started 24/10/2017
+
+The API
+*******
+
+A large part of the motivation behind the choice of Python for the HiPERCAM
+pipeline was to make it straightforward for observers to write their own
+add-ons and scripts. Real data invariably throws up exceptions to the rule
+which might require a hand-crafted approach. The pipeline API (Application
+Programmers Interface) is designed to allow you to do so.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   quickapi
+   hcmformat
+   windows
+   details
+   ../timing/timing
+   ../timing/timing_tests
+   bugs
+   logging

docs/api/bugs.rst

@@ -0,0 +1,40 @@
+.. HiPERCAM bug reports, started 21/05/2018
+
+.. include:: ../globals.rst
+
+.. _reporting_problems:
+
+Reporting problems
+******************
+
+If you encounter problems that you think are to do with the software,
+then *please* raise an "issue" on `github
+<https://github.com/HiPERCAM/hipercam>`_ where all code associated
+with |hiper| is made public. The advantage of this over e-mail
+is that all messages connected with a given problem are linked
+together, and it makes it easy to see what remains to be done. Try to
+make it one issue-per-problem.  If you e-mail me, I might well simply
+respond with "open an issue on github".
+
+The rules of the game are:
+
+  #. Know which version you are running. Either type ``pydoc hipercam`` and
+     scroll to the bottom of the page or type in a terminal::
+
+        python -c 'import hipercam; print(hipercam.version())'
+
+  #. Make sure you are up to date, i.e. compare your version with the version
+     at the top of this page which will be a number like
+     0.19.9.dev0+g52a7aac.d20200226 or 0.20.1 (the latter means its the
+     version corresponding exactly to release 0.20.1; the former means you
+     are using one developing towards 0.19.9).
+
+  #. Try to narrow down the circumstances under which the problem arises; make
+     sure it's repeatable. Specify how the problem occurs, cut-and-paste any
+     error messages that are produced.
+
+  #. Be prepared to tar or zip up a set of files (e.g. a reduce file, an
+     aperture file, etc) that cause the issue so I can try to repeat it.
+
+
+

docs/api/details.rst

@@ -0,0 +1,42 @@
+.. The full API of the HiPERCAM code
+
+.. include:: ../globals.rst
+
+Modules
+*******
+
+|hiper|'s classes and methods are spread over a number of sub-modules
+which group together related components. This pages gives a link to
+documentation auto-generated from the in-code documentation. The same
+information can be accessed from a terminal using ``pydoc``. A
+recurring feature are individual items that can be grouped into a
+bunch representing a CCD's-worth of them and then into a
+multiple-CCD's worth. Thus you will see this for windows, defects,
+apertures, fringe ampltude pairs etc.
+
+.. Note::
+
+   There is much more to be added here. TBD.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   hipercam-ccd
+   hipercam-hlog
+   hipercam-window
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

docs/api/hcmformat.rst

@@ -0,0 +1,133 @@
+.. include:: ../globals.rst
+
+|hiper|'s hcm file format
+=========================
+
+The |hiper| pipeline stores individual multi-CCD exposures in files with
+extension '.hcm'. These are in fact FITS files that can be examined with
+e.g. 'fv' or listed with 'fitshead', but the extension '.hcm' is used to
+distinguish them clearly from the raw '.fits' files and to reduce the chances
+of overwriting the latter. In order for these to be useful through the rest of
+the software, some assumptions about their internal structure are necessary,
+and they need to contain location information to show where sub-windows are
+placed within the CCDs.  The purpose of this document is to specify this in as
+much detail as possible.
+
+The basic structure of an '.hcm' file is as follows::
+
+  [General Header] [CCD 1] [CCD 2] [CCD 3] [CCD 4] [CCD 5]
+
+'General Header' here is the first HDU [HDU0] which contains no data but has
+general header information pertaining to the entire multi-CCD frame. Each CCD
+in turn has the structure::
+
+   Window 1, Window 2, Window 3, Window 4, ...
+
+Each window has some header and data. The first has some extra headers general
+to the CCD as a whole. Each window comes with a label (header item 'WINDOW').
+For |hiper| data, these have values like 'E1', 'G2', 'E', 'F', 'G' and 'H'
+denoting the quadrant of the CCD that the Window comes from. For a standard
+windowed mode, with 1 window per quadrant, there will be 4 HDUs per CCD, so a
+total of 5x4+1 = 25 HDUs. The Windows for a given CCD may come in any order,
+but they should come as a contiguous block.
+
+HDU structure and keywords
+--------------------------
+
+I now expand on this, detailing the header keywords expected. I concentrate on
+those essential for the operation of pipeline commands, |reduce| above all.
+
+1) HDU0. An hcm file starts with an HDU with no data but some header.
+
+   Header items generated from HiPERACAM raw files:
+
+      NUMCCD   : int
+         specifies the number of CCDs.
+
+      DATE     : string
+         date the run file was written if from |hiper|
+
+      GPS      : bool
+         GPS status
+
+      TIMSTAMP : string
+         time stamp associated with the individual frame
+
+      NFRAME   : int
+         frame number
+
+   Of these, 'TIMSTAMP' is essential.
+
+2) Then each CCD comes as a block of HDUs, one per Window. The header in
+   the first HDU *must* contain::
+
+      NXTOT    : int
+         maximum X-dimension, unbinned pixels to give a reference
+         size for plots of this CCD.
+
+      NYTOT    : int
+         maximum Y-dimension, unbinned pixels.
+
+      CCD      : string
+         the label of the CCD
+
+      MJDUTC   : float
+         the MJD at mid-exposure of the CCD. This might be the same as
+         TIMSTAMP of the general header, but it might not.
+
+      GOODTIME : bool
+         flag to indicate whether the time is thought to be reliable. Defaults
+         to True if not present.
+
+   It can also contain a keyword 'DSTATUS' giving a boolean that indicates
+   whether the frame contains data or not (True means yes). This is needed
+   because ULTRACAM and |hiper| have options to suspend readout ('NBLUE' and
+   'NSKIP') which lead to blank dummy frames in between the real data
+   frames. If 'DSTATUS' is not found, the CCD will be assumed to be OK.
+
+   All the HDUs in a CCD *must* contain::
+
+      CCD    : string
+         string label matching the label of the first HDU of the CCD.
+         This is used to identify which HDUs belong to a given CCD.
+
+      LLX    : int
+         X-coordinate of lower-left-most unbinned pixel that
+         contributes to the window, starting with 1 on the far
+         left.
+
+      LLY    : int
+         Y-coordinate of lower-left-most unbinned pixel that
+         contributes to the window, starting with 1 on the bottom
+
+      XBIN   : int
+         binning factor in X
+
+      YBIN   : int
+         binning factor in Y
+
+    Finally they *should* also contain::
+
+      WINDOW : string
+         a string label for the window. If it doesn't exist
+         an attempt will be made to generate labels by counting.
+
+Foreign data
+------------
+
+The format of '.hcm' files needs to be created if you want to apply the
+pipeline to data from other instruments. Since such data is typically
+FITS-format as are '.hcm' files, this might simply be a matter of adding new
+keywords and re-arranging HDUs. The script for carrying this out is
+|fits2hcm|. If you have some data, look at that script and submit new code
+through github.
+
+Example headers
+---------------
+
+Here is the result of running 'fitsheader' on a '.hcm' file which
+may make the above easier to understand. Bear in mind there are many
+extras associated with making it easier to display hcm files with 'ds9'.
+
+.. literalinclude:: ../../data/example_headers
+

docs/api/hipercam-ccd.rst

@@ -0,0 +1,23 @@
+.. The API of hipercam.window
+
+.. include:: ../globals.rst
+
+hipercam.ccd
+************
+
+.. automodule:: hipercam.ccd
+
+   .. rubric:: Classes summary
+
+   .. autosummary::
+
+      CCD
+      MCCD
+
+   .. autoclass:: CCD
+      :show-inheritance:
+      :members:
+
+   .. autoclass:: MCCD
+      :show-inheritance:
+      :members:

docs/api/hipercam-hlog.rst

@@ -0,0 +1,39 @@
+.. The API of hipercam.window
+
+.. include:: ../globals.rst
+
+hipercam.hlog
+*************
+
+.. automodule:: hipercam.hlog
+
+   .. rubric:: Classes summary
+
+   .. autosummary::
+
+      Hlog
+      Tseries
+
+   .. autoclass:: Hlog
+      :show-inheritance:
+      :members:
+
+   .. autoclass:: Tseries
+      :show-inheritance:
+      :members:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

docs/api/hipercam-window.rst

@@ -0,0 +1,48 @@
+.. The API of hipercam.window
+
+.. include:: ../globals.rst
+
+hipercam.window
+***************
+
+.. automodule:: hipercam.window
+
+   .. rubric:: Classes summary
+
+   .. autosummary::
+
+      Winhead
+      Window
+      CcdWin
+      MccdWin
+
+   .. autoclass:: Winhead
+      :show-inheritance:
+      :members:
+
+   .. autoclass:: Window
+      :show-inheritance:
+      :members:
+
+   .. autoclass:: CcdWin
+      :show-inheritance:
+      :members:
+
+   .. autoclass:: MccdWin
+      :show-inheritance:
+      :members:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+