diff --git a/CHANGELOG.rst b/CHANGELOG.rst new file mode 100644 index 0000000..dd7718c --- /dev/null +++ b/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 +`_. + +.. _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 diff --git a/README.rst b/README.rst index 76c7c0e..f06a2da 100644 --- a/README.rst +++ b/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 diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..cae03f5 --- /dev/null +++ b/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: diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 0000000..565b052 --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1 @@ +.. include:: ../CHANGELOG.rst diff --git a/docs/index.rst b/docs/index.rst index 78da06e..0fa3849 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/readme.rst b/docs/readme.rst new file mode 100644 index 0000000..72a3355 --- /dev/null +++ b/docs/readme.rst @@ -0,0 +1 @@ +.. include:: ../README.rst