Skip to content

Commit

Permalink
Port CHANGELOG.md -> CHANGELOG.rst
Browse files Browse the repository at this point in the history
The release of sphinx 3.0.0 removed some functions that's been
deprecated since v1.4. This made the sphinx-extension 'm2r' break. We
use m2r to include .md files in the sphinx-docs. Although a PR that
seemingly solves the problem is proposed [1], the sole developer of m2r
has not been active in a while. It's unknown when and if this fix will
be merge and even if, having a dependency on a unmaintained project like
m2r makes me feel a bit uneasy.

The ideal action would be to use 'recommonmark' for our .md files.
However, sphinx and recommonmark does not play nice when the .md files
is out of directory, i.e. outside python/docs [2].

That leaves us with two options, either pinning the sphinx version to
<v3.0.0 and wait for better days, with regards to better
sphinx/recommonmarks support, or port the CHANGELOG to rst. As it's
unknown whether [2] will actually see the day of light or not, porting
seems most reasonable at this point in time.

To mention it, there is a bias against using .rst for CHANGELOGs and
READMEs in the community, with the main points being that people are
generally more familiar with .md and that .md is easier and faster to
write.  But with a already well-defined structure to our CHANGELOG, the
overhead is minimal.

[1] miyakogi/m2r#55
[2] sphinx-doc/sphinx#7000
  • Loading branch information
ErlendHaa committed Apr 19, 2020
1 parent 0067e17 commit 9ec056d
Show file tree
Hide file tree
Showing 5 changed files with 119 additions and 112 deletions.
109 changes: 0 additions & 109 deletions CHANGELOG.md

This file was deleted.

118 changes: 118 additions & 0 deletions CHANGELOG.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
Changelog
=========
All notable changes to this project will be documented in this file, for a
complete overview of changes, please refer to the git log.

The format is based on `Keep a Changelog`_,
but most notably, without sectioning changes into type-of-change.

0.1.16_ - 2010.01.16
--------------------
* Fixes a bug were ``dlisio.load()`` did not properly close the memory mapping to
the file when loading failed.
* Fixes a bug where ``dlis.match()`` and ``dlis.object()`` returned the same object
multiple times under certain circumstances.
* ``dlis.describe()`` again includes the object-count of each object-type.
* ``dlisio.load()`` now warns if a file contains ``Update``-objects. The current lack
of support for such objects means that dlisio may wrongfully present data in
files with ``Update``-objects.
* There is now a list of organization codes on readthedocs
* Fixes a bug in the Process-docs

0.1.15_ - 2019.12.18
--------------------
* Metadata objects are now parsed and loaded when needed, rather than all at
once in ``dlisio.load()``. This is not directly observable for the user, other
than it improves performance for ``dlisio.load()``. For files with a lot of
metadata, the performance gain is huge.
* dlisio can now read even more curve-data. Specifically, where multiple FDATA
(rows) are stored in the same IFLR.
* The array from ``Frame.curves()`` now includes FRAMENO as the first column.
FRAMENO are the row numbers as represented in the file. It might happen that
there are missing rows or that they are out-of-order in the file, that is now
observable by inspecting FRAMENO.
* Better support for non-ascii strings. It is now possible to tell dlisio which
string encodings to try if decoding with 'utf-8' fails. Supply a list of
encodings o ``set_encodings()`` and dlisio will try them in order.
* ``Frame.index`` now returns the Channel mnemonic, not the ``Channel``-object.
* ``Channel.index`` is removed.
* Validated types are now represented as tuples, not lists.
* Fixes a bug were microseconds in datetime objects were interpreted as
milliseconds.
* Better error message when incomplete Channels objects cause parsing of curves
to fail as a result.

0.1.14_ - 2019.10.14
--------------------
* dlisio has learned to read curves with variable length data types. Thus,
every data-type that the standard allows for curves is now supported by
dlisio.
* ``Frame``- and ``Channel``-objects now have an index-property. ``index`` returns the
``Channel``-object that serves as the index-channel for the given Frame/Channel.

0.1.13_ - 2019.10.3
-------------------
* The sphinx documentation on readthedocs_ has a few new sections: About the
project, an introduction to some dlis-concepts and a quick guide to help new
users to get started with dlisio.
* API documentation has seen some improvements as well. The ``dlis``-class
documentation is revamped to better help users to work with logical files and
accessing objects. ``Frame`` and ``Channel`` are more thoroughly documented, and
more examples on how to work with curve data are provided.
* Direct access to specific objects has been made more convenient with
``dlis.object()``.
* ``dlis.match()`` is no longer case sensitive.
* ``dlis.fileheader`` now returns the ``Fileheader``-object directly, not wrapped as
dict_values.
* ``dlis.objects`` has been removed
* CircleCI is added to the ci-pipeline for building and testing on linux
* Python test suite has seen some refactoring
* It is now possible to build the python module with ``setup.py``, provided the
core library is already installed on the system.

0.1.12_ - 2019.08.15
--------------------
* Output a readable summary of any metadata-object, logical file or batch-object
with ``.describe()``.
* Access to curves directly through ``Frame``- and ``Channel``-objects.
* dlisio has learned to read the following metadata-objects: ``Process``, ``Path``,
``Splice``, ``Well reference point``, ``Group``, ``Message``, ``Comment``.
* ``dlis.match()`` lets you search for objects with a regular expression.
* dlisio now reads even more files. Restrictions such as number-of-objects in an
object_set and missing representation codes in templates have been lifted.
* The parsing routine has seen some improvements. This includes giving the user
more freedom to customize object-parsing.
* Multidimensional metadata attributes are handled correctly.
* ``BasicObject.update_stash`` has been removed.
* ``dlis.getobjects()`` has been removed.
* ``dlis.object_set`` has been renamed to ``dlis.indexedobjects``.
* ``Computation.source`` is now a scalar, not vector.
* ``BasicObject``'s ``type`` and ``attic`` is now attributes, not properties.
* Objects are allowed to have empty ids (name/mnemonic).
* The API documentation has seen some minor updates.
* dlisio uses endianness.h rather than its own implementation.
* Some of the binary test files have been simplified.
* core functionality such as ``findfdata``, ``findsul``, ``findvrl``, ``findoffsets`` and
``stream.at`` are more thoroughly tested.
* Parts of the Python test suite have been refactored.
* Fixed a bug were long obnames were allocated insufficient memory.
* Fixed a bug were multi-dimensional fdata were interpreted incorrectly.
* Fixed a bug that caused incorrectly partitioning from physical- to logical
file(s).
* Fixed a bug that caused parsing of a encrypted logical record to fail.

0.1.11_ - 2019.06.04
--------------------
* Support for logical files - dlisio now partitions the loaded physical file
into logical files. This has resulted in a behavioral change were
``dlisio.load()`` now returns a tuple-like object of n-logical files.

.. _`Keep a changelog`: https://keepachangelog.com/en/1.0.0/
.. _readthedocs: https://dlisio.readthedocs.io/en/stable/

.. _0.1.16: https://github.com/equinor/dlisio/compare/v0.1.15...v0.1.16
.. _0.1.15: https://github.com/equinor/dlisio/compare/v0.1.14...v0.1.15
.. _0.1.14: https://github.com/equinor/dlisio/compare/v0.1.13...v0.1.14
.. _0.1.13: https://github.com/equinor/dlisio/compare/v0.1.12...v0.1.13
.. _0.1.12: https://github.com/equinor/dlisio/compare/v0.1.11...v0.1.12
.. _0.1.11: https://github.com/equinor/dlisio/compare/v0.1.10...v0.1.11
2 changes: 1 addition & 1 deletion python/docs/changelog.rst
Original file line number Diff line number Diff line change
@@ -1 +1 @@
.. mdinclude:: ../../CHANGELOG.md
.. include:: ../../CHANGELOG.rst
1 change: 0 additions & 1 deletion python/docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,6 @@
'sphinx.ext.intersphinx',
'sphinx.ext.imgmath',
'sphinx.ext.autosectionlabel',
'm2r'
]

autosummary_generate = True
Expand Down
1 change: 0 additions & 1 deletion python/requirements-dev.txt
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,4 @@ pytest-runner
pybind11
hypothesis
sphinx
m2r
scikit-build

0 comments on commit 9ec056d

Please sign in to comment.