Fix structure to match Python Packaging User Guide

CHANGES.rst → CHANGES.md

-Changelog
-=========
+# Changelog
 
-2.0.0 (2022-02-x)
-------------------
+## 2.0.0 (2022-02-x)
 
 - Compatible with ICARTT v2 standard
 - Formats 1001 and 2110
-- Internal overhaul
+- Complete internal overhaul
 
-1.0.0 (2017-12-19)
-------------------
+## 1.0.0 (2017-12-19)
 
 - Peer-reviewed version to be published in Knote et al., GMD
 
-0.1.0 (2017-08-12)
-------------------
+## 0.1.0 (2017-08-12)
 
 - Initial release

INSTALL.md

+`pip install icartt`
\ No newline at end of file

INSTALL.rst

-::
-
-    pip install icartt

MANIFEST.in

-include CHANGES.rst
-include INSTALL.rst
-include LICENSE.txt
-include README.rst
+include CHANGES.md
+include INSTALL.md
+include LICENSE
+include README.md

README.md

-icartt
-======
+# icartt
 
 ``icartt`` is an ICARTT format reader and writer
 
-Documentation
-=============
+## Documentation
 
 Please have a look at docs/source/usage.rst for usage examples. Full documentation is in preparation.
 
-Contributing
-============
+## Contributing
 
 We are happy to receive your [new issue report](https://mbees.med.uni-augsburg.de/gitlab/mbees/icartt_pypackage/-/issues/new).
 
@@ -17,8 +14,7 @@ If you'd like to contribute source code directly, please [create a fork](https:/
 make your changes and then [submit a merge request](https://mbees.med.uni-augsburg.de/gitlab/mbees/icartt_pypackage/-/merge_requests/new) to the original project.
 
 
-Installation
-============
+## Installation
 
 Clone this repository / or your fork and install as "editable":
 

docs/source/conf.py

@@ -46,7 +46,7 @@ exclude_patterns = []
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'classic'
 
 # 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,

docs/source/index.rst

@@ -3,8 +3,9 @@
    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 for Python
 
@@ -15,39 +16,39 @@ The ICARTT data format is described here: https://www-air.larc.nasa.gov/missions
    :caption: Contents:
 
 Installation
-------------
+############
 
-.. include:: ../../INSTALL.rst
+.. include:: ../../INSTALL.md
 
 Example
-------------
+#######
 
 .. include:: usage.rst
 
 API
-----
+###
 
 .. module:: icartt
 
 Variable
-^^^^^^^^^^
+********
 
 .. autoclass:: Variable
    :members:
 
 Dataset
-^^^^^^^^^^
+********
 
 .. autoclass:: Dataset
    :members:
 
 Formats
-^^^^^^^^^^
+********
 
 .. autoenum:: Formats
 
 Indices and tables
-==================
+###################
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/source/usage.rst

-Reading an existing dataset
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Reading an existing dataset 
+############################
 
-::
+Simple format (FFI 1001)
+*************************
 
-   import icartt
+.. literalinclude:: ../../tests/usage_examples/read_ffi1001.py
 
-   # load a new dataset from an existing file
-   ict = icartt.Dataset('tests/examples/DC8-20160517.ict')
+More complex (FFI 2110)
+*************************
 
-   # list variable names
-   [ x for x in ict.variables ]
+Identical to FFI1001, only the data structure is more complex:
 
-   # get data for variable 'UTC' (shortcut):
-   ict.data['UTC']
+.. literalinclude:: ../../tests/usage_examples/read_ffi2110.py
 
-   # get all data as NumPy array:
-   ict.data.data
+Creating a new dataset 
+############################
 
-   # read some metadata
-   ict.PIName
-   ict.PIAffiliation
-   ict.missionName
-   ict.dataSourceDescription
+Simple format (FFI 1001)
+*************************
 
-   # some info on a variable
-   ict.variables['Alt_ft'].units
-   ict.variables['Alt_ft'].miss
+.. literalinclude:: ../../tests/usage_examples/create_ffi1001.py
 
+More complex (FFI 2110)
+*************************
 
-Creating a new dataset
-^^^^^^^^^^^^^^^^^^^^^^^
+Again, like for FFI 1001 but more complex data structure
 
-::
-
-   import icartt
-   import datetime
-
-   ict                                    = icartt.Dataset(format=icartt.Formats.FFI1001)
-
-   ict.PIName                             = 'Knote, Christoph'
-   ict.PIAffiliation                      = 'Faculty of Medicine, University Augsburg, Germany'
-   ict.dataSourceDescription              = 'Example data'
-   ict.missionName                        = 'MBEES'
-   ict.dateOfCollection                   = datetime.datetime.today()
-   ict.dateOfRevision                     = datetime.datetime.today()
-
-   ict.dataIntervalCode                   = [ 0 ]
-
-   ict.independentVariable                = icartt.Variable(  'Time_Start',
-                                                               'seconds_from_0_hours_on_valid_date',
-                                                               'Time_Start',
-                                                               'Time_Start',
-                                                               vartype=icartt.VariableType.IndependentVariable,
-                                                               scale=1.0, miss=-9999999)
-
-   ict.dependentVariables['Time_Stop']    = icartt.Variable(   'Time_Stop',
-                                                               'seconds_from_0_hours_on_valid_date',
-                                                               'Time_Stop',
-                                                               'Time_Stop',
-                                                               scale=1.0, miss=-9999999)
-
-   ict.dependentVariables['Payload']      = icartt.Variable(   'Payload',
-                                                               'some_units',
-                                                               'Payload',
-                                                               'Payload',
-                                                               scale=1.0, miss=-9999999)
-
-   ict.specialComments.append("Some comments on this dataset:")
-   ict.specialComments.append("They are just examples!")
-   ict.specialComments.append("Adapt as needed.")
-
-   ict.endDefineMode()
-
-   # Three ways to add data:
-
-   # 1) simple (single data line)
-   ict.data.add( Time_Start = 12.3, Time_Stop = 12.5, Payload = 23789423.2e5 )
-
-   # Let's check:
-   ict.write()
-
-   # 2) as dictionary (single data line)
-   mydict = { 'Time_Start': 12.6, 'Time_Stop': 13.1, 'Payload': 324235644.1e5 }
-   ict.data.add( **mydict )
-   # (note, exploding the dictionary is necessary)
-
-   # 3) as NumPy array (bulk)
-   import numpy as np
-   data = np.array( [ (13.4, 14.0, 2348925e5), (14.1, 14.9, 23425634e5) ] )
-   ict.data.addBulk( data )
-
-   # Note 1: you are responsible to ensure that the order of elements in a data line
-   # corresponds to variable listing below:
-   print( [ x for x in ict.variables ] )
-
-   # Note 2: for single lines, you still need to make it an array!
-   data = np.array( [ (15.4, 15.0, 52452495290e5) ] )
-   ict.data.addBulk( data )
-
-   # Now write to file:
-   with open('path/to/output.ict', 'w') as f:
-      ict.write(f=f)
+.. literalinclude:: ../../tests/usage_examples/create_ffi1001.py

pyproject.toml

+[build-system]
+requires = [
+    "numpy", "setuptools"
+]
+build-backend = "setuptools.build_meta"

setup.cfg

+[metadata]
+name = icartt
+version = 1.9.1
+author = Christoph Knote
+author_email = christoph.knote@med.uni-augsburg.de
+description = ICARTT format reader and writer
+long_description = file: README.md, INSTALL.md, CHANGES.md
+long_description_content_type = text/markdown
+url = https://mbees.med.uni-augsburg.de
+project_urls = 
+    Bug Tracker = http://mbees.med.uni-augsburg.de/gitlab/mbees/icartt_pypackage/issues
+classifiers = 
+    Programming Language :: Python :: 3
+    Development Status :: 5 - Production/Stable
+    Environment :: Console
+    Intended Audience :: Developers
+    Intended Audience :: Education
+    Intended Audience :: End Users/Desktop
+    Intended Audience :: Science/Research
+    License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+    Operating System :: POSIX
+    Topic :: Education
+    Topic :: Scientific/Engineering
+    Topic :: Utilities
+
+[options]
+package_dir =
+    = src
+packages = find:
+python_requires = >=3.0
+
+[options.packages.find]
+where = src

setup.py

-import os
-from setuptools import setup
-
-def read(filename):
-    with open(os.path.join(os.path.dirname(__file__), filename)) as f:
-        return f.read()
-
-setup(name='icartt',
-      description='ICARTT format reader and writer',
-      long_description=read('README.md') + '\n\n' + read('INSTALL.rst') + '\n\n' + read('CHANGES.rst'),
-      long_description_content_type='text/markdown',
-      version='1.9.1',
-      url='https://mbees.med.uni-augsburg.de',
-      author='Christoph Knote',
-      author_email='christoph.knote@med.uni-augsburg.de',
-      license='GPLv3',
-      classifiers=[
-            'Development Status :: 5 - Production/Stable',
-            'Environment :: Console',
-            'Intended Audience :: Developers',
-            'Intended Audience :: Education',
-            'Intended Audience :: End Users/Desktop',
-            'Intended Audience :: Science/Research',
-            'License :: OSI Approved :: GNU General Public License v3 (GPLv3)',
-            'Operating System :: POSIX',
-            'Programming Language :: Python :: 3',
-            'Topic :: Education',
-            'Topic :: Scientific/Engineering',
-            'Topic :: Utilities'
-        ],
-      keywords='',
-      packages=['icartt'],
-      test_suite = 'tests',
-      tests_require = [],
-      zip_safe=False)