Add a changelog and restructure the documentation

CHANGELOG.rst

@@ -0,0 +1,112 @@
+Changelog
+=========
+
+The purpose of this document is to list all of the notable changes to this
+project. The format was inspired by `Keep a Changelog`_. This project adheres
+to `semantic versioning`_.
+
+.. contents::
+   :local:
+
+.. _Keep a Changelog: http://keepachangelog.com/
+.. _semantic versioning: http://semver.org/
+
+`Release 0.5`_ (2017-06-24)
+---------------------------
+
+- Added ``linux_utils.atomic`` module (atomic filesystem operations).
+- Expose parsed NFS information in ``FileSystemEntry`` objects.
+- Test coverage improvements and minor code changes.
+- Consistently define ``__all__`` for modules.
+
+.. _Release 0.5: https://github.com/xolox/python-linux-utils/compare/0.4.1...0.5
+
+`Release 0.4.1`_ (2017-06-23)
+-----------------------------
+
+A "vanity release" to add missing links in the README because the missing links
+caused PyPI to render the readme on the project page as plain text instead of
+reStructuredText converted to HTML :-).
+
+.. _Release 0.4.1: https://github.com/xolox/python-linux-utils/compare/0.4...0.4.1
+
+`Release 0.4`_ (2017-06-22)
+---------------------------
+
+Added the command line programs ``cryptdisks-start-fallback`` and
+``cryptdisks-stop-fallback``. My reason for adding these was so that I could
+refer to them in the documentation of my rsync-system-backup_ package:
+`How to set up unattended backups to an encrypted USB disk
+<http://rsync-system-backup.readthedocs.io/en/latest/howto/encrypted-usb-disk.html#unlock-the-encrypted-disk>`_.
+
+.. _Release 0.4: https://github.com/xolox/python-linux-utils/compare/0.3...0.4
+
+`Release 0.3`_ (2017-06-21)
+---------------------------
+
+Improved ``/etc/crypttab`` compatibility:
+
+- Support for ``LABEL="..."`` device identifiers.
+- Respect the ``/etc/crypttab`` options ``discard``, ``readonly`` and ``tries``.
+- Ignore encrypted filesystems that aren't LUKS.
+
+.. _Release 0.3: https://github.com/xolox/python-linux-utils/compare/0.2...0.3
+
+`Release 0.2`_ (2017-06-21)
+---------------------------
+
+Added a Python API for ``cryptsetup`` (to control LUKS full disk encryption)
+including Python emulation of ``cryptdisks_start`` and ``cryptdisks_stop``.
+
+This functionality is making it easier for me to write test suites for Python
+projects that involve disk encryption, for example crypto-drive-manager_ and
+rsync-system-backup_.
+
+.. _Release 0.2: https://github.com/xolox/python-linux-utils/compare/0.1...0.2
+
+`Release 0.1`_ (2017-06-21)
+---------------------------
+
+The initial release of ``linux-utils`` supports parsing of the ``/etc/fstab``
+(``/proc/mounts``) and ``/etc/crypttab`` configuration file formats based on a
+"generic tabfile" parser. The "history" section of the readme explains why this
+project came to be:
+
+----
+
+Back in 2015 I wrote some Python code to parse the Linux configuration files
+``/etc/fstab`` and ``/etc/crypttab`` for use in crypto-drive-manager_. Fast
+forward to 2017 and I found myself wanting to use the same functionality
+in rsync-system-backup_. Three options presented themselves to me:
+
+1. **Copy/paste the relevant code.** Having to maintain the same code in
+   multiple places causes lower quality code because having to duplicate the
+   effort of writing documentation, developing tests and fixing bugs is a very
+   demotivating endeavor. In fact sometime in 2016 I *did* copy/paste parts of
+   this code into a project at work, because I needed similar functionality
+   there. Of course since then the two implementations diverged :-p.
+
+2. **Make crypto-drive-manager a dependency of rsync-system-backup.** Although
+   this approach is less ugly than copy/pasting the code, it still isn't
+   exactly elegant because the two projects have nothing to do with each other
+   apart from working with LUKS encrypted disks on Linux.
+
+3. **Extract the functionality into a new package.** In my opinion this was
+   clearly the most elegant approach, unfortunately it also required the most
+   work from me :-). On the plus side I've published linux-utils with a test
+   suite which means less untested code remains in crypto-drive-manager_ (which
+   doesn't have a test suite at the time of writing).
+
+While extracting the code I shortly considered integrating the functionality
+into debuntu-tools_, however the ``/etc/fstab`` and ``/etc/crypttab`` parsing
+isn't specific to Debian or Ubuntu at all and debuntu-tools_ has several
+dependencies that aren't relevant to Linux configuration file parsing.
+
+Tangentially related: The reason I went with the extremely generic name
+`linux-utils` is because I will be adding more *"specific to Linux but not
+Debian"* functionality to this package in the very near future :-).
+
+.. _Release 0.1: https://github.com/xolox/python-linux-utils/tree/0.1
+.. _debuntu-tools: https://pypi.python.org/pypi/debuntu-tools
+.. _rsync-system-backup: https://pypi.python.org/pypi/rsync-system-backup
+.. _crypto-drive-manager: https://pypi.python.org/pypi/crypto-drive-manager

README.rst

@@ -140,9 +140,9 @@ Contact
 -------
 
 The latest version of `linux-utils` is available on PyPI_ and GitHub_. The
-documentation is hosted on `Read the Docs`_. For bug reports please create an
-issue on GitHub_. If you have questions, suggestions, etc. feel free to send me
-an e-mail at `peter@peterodding.com`_.
+documentation is available on `Read the Docs`_ and includes a changelog_. For
+bug reports please create an issue on GitHub_. If you have questions,
+suggestions, etc. feel free to send me an e-mail at `peter@peterodding.com`_.
 
 License
 -------
@@ -151,10 +151,9 @@ This software is licensed under the `MIT license`_.
 
 © 2018 Peter Odding.
 
-.. External references:
-
 .. _/etc/crypttab: https://manpages.debian.org/crypttab
 .. _/etc/fstab: https://manpages.debian.org/fstab
+.. _changelog: https://linux-utils.readthedocs.org/en/latest/changelog.html
 .. _cryptdisks_start: https://manpages.debian.org/cryptdisks_start
 .. _cryptdisks_stop: https://manpages.debian.org/cryptdisks_stop
 .. _crypto-drive-manager: https://pypi.python.org/pypi/crypto-drive-manager

docs/api.rst

@@ -0,0 +1,52 @@
+API documentation
+=================
+
+The following documentation is based on the source code of version |release| of
+the `linux-utils` package.
+
+**Available modules**
+
+.. contents::
+   :local:
+
+:mod:`linux_utils`
+------------------
+
+.. automodule:: linux_utils
+   :members:
+
+:mod:`linux_utils.atomic`
+-------------------------
+
+.. automodule:: linux_utils.atomic
+   :members:
+
+:mod:`linux_utils.cli`
+----------------------
+
+.. automodule:: linux_utils.cli
+   :members:
+
+:mod:`linux_utils.crypttab`
+---------------------------
+
+.. automodule:: linux_utils.crypttab
+   :members:
+
+:mod:`linux_utils.fstab`
+------------------------
+
+.. automodule:: linux_utils.fstab
+   :members:
+
+:mod:`linux_utils.luks`
+-----------------------
+
+.. automodule:: linux_utils.luks
+   :members:
+
+:mod:`linux_utils.tabfile`
+--------------------------
+
+.. automodule:: linux_utils.tabfile
+   :members:

docs/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGELOG.rst

docs/index.rst

@@ -1,54 +1,32 @@
-.. include:: ../README.rst
+linux-utils: Linux system administration tools for Python
+=========================================================
 
-API documentation
-=================
-
-The following documentation is based on the source code of version |release| of
-the `linux-utils` package.
-
-**Available modules**
+Welcome to the documentation of `linux-utils` version |release|!
+The following sections are available:
 
 .. contents::
    :local:
 
-:mod:`linux_utils`
+User documentation
 ------------------
 
-.. automodule:: linux_utils
-   :members:
-
-:mod:`linux_utils.atomic`
--------------------------
-
-.. automodule:: linux_utils.atomic
-   :members:
+The readme is the best place to start reading, it's targeted at all users:
 
-:mod:`linux_utils.cli`
-----------------------
+.. toctree::
+   readme.rst
 
-.. automodule:: linux_utils.cli
-   :members:
-
-:mod:`linux_utils.crypttab`
----------------------------
-
-.. automodule:: linux_utils.crypttab
-   :members:
-
-:mod:`linux_utils.fstab`
-------------------------
+API documentation
+-----------------
 
-.. automodule:: linux_utils.fstab
-   :members:
+The following API documentation is automatically generated from the source code:
 
-:mod:`linux_utils.luks`
------------------------
+.. toctree::
+   api.rst
 
-.. automodule:: linux_utils.luks
-   :members:
+Change log
+----------
 
-:mod:`linux_utils.tabfile`
---------------------------
+The change log lists notable changes to the project:
 
-.. automodule:: linux_utils.tabfile
-   :members:
+.. toctree::
+   changelog.rst

docs/readme.rst

@@ -0,0 +1 @@
+.. include:: ../README.rst