diff --git a/docs/Makefile b/docs/Makefile index 4ab44d438ef30b2a168d054124cfc45efc51ff23..d0c3cbf1020d5c292abdedf27627c6abe25e2293 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,12 +1,12 @@ # Minimal makefile for Sphinx documentation # -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = python -msphinx -SPHINXPROJ = ICARTT -SOURCEDIR = . -BUILDDIR = _build +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build # Put it first so that "make" without argument is like "make help". help: @@ -17,4 +17,4 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 4965bacda53d6a1b41db690f53b5eb5a83a64977..0000000000000000000000000000000000000000 --- a/docs/conf.py +++ /dev/null @@ -1,176 +0,0 @@ -# -*- coding: utf-8 -*- -# -# ICARTT documentation build configuration file, created by -# sphinx-quickstart on Thu Jul 27 15:24:17 2017. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['sphinx.ext.autodoc'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'icartt' -copyright = u'2017, Christoph Knote' -author = u'Christoph Knote' - -# 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. -# -import pkg_resources -v = pkg_resources.get_distribution(project).version - -# The short X.Y version. -version = unicode(".".join(v.split(".")[0:2])) -# The full version, including alpha/beta/rc tags. -release = unicode(v) - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - -autodoc_default_flags = ['members'] -autodoc_member_order = 'groupwise' - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'alabaster' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# This is required for the alabaster theme -# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars -html_sidebars = { - '**': [ - 'about.html', - 'navigation.html', - 'relations.html', # needs 'show_related': True theme option to display - 'searchbox.html', - 'donate.html', - ] -} - - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = 'ICARTTdoc' - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'ICARTT.tex', u'ICARTT Documentation', - u'Christoph Knote', 'manual'), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'icartt', u'ICARTT Documentation', - [author], 1) -] - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'ICARTT', u'ICARTT Documentation', - author, 'ICARTT', 'ICARTT file reader and writer.', - 'Miscellaneous'), -] - - - diff --git a/docs/make.bat b/docs/make.bat index d4412884a493aaff580038846785df9cc0d32057..6247f7e231716482115f34084ac61030743e0715 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -5,32 +5,31 @@ pushd %~dp0 REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=python -msphinx + set SPHINXBUILD=sphinx-build ) -set SOURCEDIR=. -set BUILDDIR=_build -set SPHINXPROJ=ICARTT +set SOURCEDIR=source +set BUILDDIR=build if "%1" == "" goto help %SPHINXBUILD% >NUL 2>NUL if errorlevel 9009 ( echo. - echo.The Sphinx module was not found. Make sure you have Sphinx installed, - echo.then set the SPHINXBUILD environment variable to point to the full - echo.path of the 'sphinx-build' executable. Alternatively you may add the - echo.Sphinx directory to PATH. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. echo. echo.If you don't have Sphinx installed, grab it from echo.http://sphinx-doc.org/ exit /b 1 ) -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% goto end :help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% :end popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000000000000000000000000000000000000..618c2f816e8ba2e1b2df9bba47c21a4dc23ba957 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,55 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'ICARTT' +copyright = '2022, Christoph Knote' +author = 'Christoph Knote' + +# The full version, including alpha/beta/rc tags +release = '2.0' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..e9e980e97a5773db40fef89bd2c1fac77a901246 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,69 @@ +.. ICARTT documentation master file, created by + sphinx-quickstart on Thu Feb 10 09:33:37 2022. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +icartt +============================ + +icartt is an ICARTT file format reader and writer + +The ICARTT data format is described here: https://www-air.larc.nasa.gov/missions/etc/IcarttDataFormat.htm + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +Installation +------------ + +.. include:: ../../icartt/INSTALL.rst + +Example +------------ + +:: + + import icartt + + # load a new dataset from an existing file + ict = icartt.Dataset('path/to/example.ict') + + # list variable names + ict.varnames + # e.g. ['Fractional_Day', 'UTC', 'JDAY', 'INDEX', 'FLIGHT', 'LOCAL_SUN_TIME', ... + + # get data for variable 'UTC': + ict['UTC'] + + # some metadata + ict.organization + ict.dataSource + ict.mission + + # write to (other) file: + with open('path/to/output.ict', 'wb') as f: + ict.write(f) + +API +---- + +.. module:: icartt + +Variable +^^^^^^^^^^ + +.. autoclass:: Variable + + +Dataset +^^^^^^^^^^ + +.. autoclass:: Dataset + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/index.rst b/docs/source/old_index.rst similarity index 100% rename from docs/index.rst rename to docs/source/old_index.rst diff --git a/icartt/dataset.py b/icartt/dataset.py index 7d8c596ff315afeb4342de5f2c9ef5f72579046e..28555a63f656fcc2f37139da0713264978572402 100644 --- a/icartt/dataset.py +++ b/icartt/dataset.py @@ -1,7 +1,7 @@ import datetime import sys import collections -import decimal +import re import math import string import warnings @@ -458,7 +458,7 @@ class Dataset: elif self.format == 2110: nul = self.extract_items_1001(raw) else: - print("huh?") + warnings.warn("Unknown file format: {:d}, could not read data.".format(self.format)) self.input_fhandle.close() diff --git a/tests/test_dataset.py b/tests/test_dataset.py index 004da513454b42d0cade54baeaf10a7c2aeacab6..3571d04397d4e81842e66b9e8883095c6b179b76 100644 --- a/tests/test_dataset.py +++ b/tests/test_dataset.py @@ -4,7 +4,7 @@ import io import sys import icartt -def compare_files(str_in, str_out, skiplines=0, nlines=-1): # pragma: no cover +def compare_files(fn, str_in, str_out, skiplines=0, nlines=-1): # pragma: no cover str_out.seek(0) str_in.seek(0) input = str_in.readlines() @@ -49,7 +49,7 @@ def compare_files(str_in, str_out, skiplines=0, nlines=-1): # pragma: no cover pass if not valid_data_line and not valid_var_line: - print("Line {:d} differs:".format(i)) + print("{:s}: line {:d} differs:".format(fn, i)) print(" input: {:s}".format(inline)) print(" output: {:s}".format(outline)) @@ -137,7 +137,7 @@ class Simple1001TestCase(unittest.TestCase): ict.write_header(str_out) - self.assertTrue( compare_files(str_in, str_out, nlines=self.nheader) ) + self.assertTrue( compare_files(self.fn, str_in, str_out, nlines=self.nheader) ) def test_write_data(self): ict = icartt.Dataset(self.fn, loadData=True) @@ -147,7 +147,7 @@ class Simple1001TestCase(unittest.TestCase): ict.write(str_out) - self.assertTrue( compare_files(str_in, str_out, skiplines=self.nheader) ) + self.assertTrue( compare_files(self.fn, str_in, str_out, skiplines=self.nheader) ) def test_write(self): ict = icartt.Dataset(self.fn, loadData=True) @@ -157,7 +157,7 @@ class Simple1001TestCase(unittest.TestCase): ict.write(str_out) - self.assertTrue( compare_files(str_in, str_out) ) + self.assertTrue( compare_files(self.fn, str_in, str_out) ) fns = [ os.path.join("tests", "examples", fn) for fn in os.listdir(os.path.join("tests", "examples")) if fn.endswith(".ict")] @@ -186,7 +186,7 @@ class BulkIOTestCase(unittest.TestCase): ict.write_header(str_out) - self.assertTrue( compare_files(str_in, str_out, nlines=ict.nheader) ) + self.assertTrue( compare_files(fn, str_in, str_out, nlines=ict.nheader) ) def test_write(self): for fn in fns: @@ -198,7 +198,7 @@ class BulkIOTestCase(unittest.TestCase): ict.write(str_out) - self.assertTrue( compare_files(str_in, str_out) ) + self.assertTrue( compare_files(fn, str_in, str_out) ) if __name__ == '__main__': # pragma: no cover unittest.main()