Feature/docs (#51)

* Updated module docstrings.

* Updated README.md with roadmap.

* Updated docs index.rst.

* Improved bug-report issue template.

.github/ISSUE_TEMPLATE/bug_report.md → .github/ISSUE_TEMPLATE/bug-report.md

@@ -11,17 +11,17 @@ assignees: ''
 A clear and concise description of what the bug is.
 
 **To Reproduce**
-Steps to reproduce the behavior:
+Steps to reproduce the behavior. Please link to relevant MKV or track files to reproduce the issue.
 
 **Expected behavior**
 A clear and concise description of what you expected to happen.
 
 **Screenshots**
 If applicable, add screenshots to help explain your problem.
 
-**Desktop (please complete the following information):**
- - OS: [e.g. macOS]
- - Version: [e.g. 10.14]
+**Software (please complete the following information):**
+ - OS: [e.g. macOS 10.14]
+ - MKVToolNix version [e.g. v44.0.0]
 
 **Additional context**
 Add any other context about the problem here.

README.md

@@ -3,21 +3,52 @@
 [![License](https://img.shields.io/github/license/sheldonkwoodward/pymkv.svg)](https://github.com/sheldonkwoodward/pymkv/LICENSE.txt)
 [![Code Quality](https://api.codacy.com/project/badge/Grade/e1fe077d95f74a5886c557024777c26c)](https://api.codacy.com/project/badge/Grade/e1fe077d95f74a5886c557024777c26c)
 
-pymkv is a Python wrapper for mkvmerge. It provides support for muxing, splitting, linking, chapters, tags, and attachments through the use of mkvmerge.
+pymkv is a Python wrapper for mkvmerge and other tools in the MKVToolNix suite. It provides support for muxing,
+splitting, linking, chapters, tags, and attachments through the use of mkvmerge.
 
 ## About pymkv
-pymkv is a Python 3 library for manipulating MKV files with mkvmerge. Previously, I was constructing mkvmerge commands manually. They were becoming overly complex and unmanageable. To remedy this, I decided to write this library to make mkvmerge more scriptable and easier to use. Please open new issues for any bugs you find, support is greatly appreciated!
+pymkv is a Python 3 library for manipulating MKV files with mkvmerge. Constructing mkvmerge commands manually can
+quickly become confusing and complex. To remedy this, I decided to write this library to make mkvmerge more
+scriptable and easier to use. Please open new issues for any bugs you find, support is greatly appreciated!
 
 ## Installation
-mkvmerge must be installed on your computer. It is recommended to add it to your \$PATH variable but a different path can be manually specified. mkvmerge can be found and downloaded from [here] or in most package managers.
+mkvmerge must be installed on your computer, it is needed to process files when creating MKV objects. It is also
+recommended to add it to your $PATH variable but a different path can be manually specified. mkvmerge can be found
+and downloaded from [here](https://mkvtoolnix.download/downloads.html) or from most package managers.
 
 To install pymkv from PyPI, use the following command:
 
     $ pip install pymkv
 
-You can also clone the repo and run the following command in the project root to edit the source code:
+You can also clone the repo and run the following command in the project root to install the source code as editable:
 
     $ pip install -e .
 
 ## Documentation
-The documentation for pymkv can be found [here](https://pymkv.shel.dev) or in the docstrings.
+The documentation for pymkv can be found [here](https://pymkv.shel.dev) or in the project's docstrings.
+
+## Roadmap
+pymkv was a project started a few years ago when I was first learning Python. There were a number of things that I
+did that could use improvement. The planned changes and future features are outlined below. Keep an eye on the [Github
+Projects page](https://github.com/sheldonkwoodward/pymkv/projects) for the current roadmap status.
+
+### ~~Documentation~~
+The current documentation for pymkv is lacking. Instead of manually managing a GitHub Wiki, Sphinx will be setup to
+automatically generate documentation from docstrings. The docstrings will also need to be updated and improved to
+ensure this documentation is complete.
+
+### Tests
+After completing documentation for the existing features, unit tests need to be written to "lock in" the existing
+functionality. Generating mkvmerge commands can be complex and it is easy to subtly modify an existing feature when
+adding a new one. Unit tests will ensure that features remain the same and help prevent bugs in the future.
+
+### Cleanup
+The existing code base could use some tidying, better commenting, debugging, and a general styling overhaul. Setting up
+[pre-commit](https://pre-commit.com/) and the [Black code formatter](https://github.com/psf/black) will help keep the
+code base more readable and maintainable.
+
+### Features
+Once these first three steps are complete, pymkv will be ready to start adding new features. The goal is for pymkv to
+implement the functionality of mkvmerge and other MKVToolNix tools as closely as possible. New features and bugs will
+be added to the [GitHub issues page](https://github.com/sheldonkwoodward/pymkv/issues). As pymkv progresses through
+the previous steps, this roadmap will be expanded to outline new features.

docs/source/index.rst

@@ -1,11 +1,20 @@
-Home
-====
+pymkv
+=====
 
-Welcome the pymkv documentation!
+Welcome to the pymkv documentation! Here you will find links to the core modules and examples of how to use each.
 
 Modules
 -------
 
+The three primary modules of pymkv are :class:`~pymkv.MKVFile`, :class:`~pymkv.MKVTrack`, and
+:class:`~pymkv.MKVAttachment`. The :class:`~pymkv.MKVFile` class is used to import existing or create new MKV files.
+The :class:`~pymkv.MKVTrack` class is used to add individual tracks to an :class:`~pymkv.MKVFile`. The
+:class:`~pymkv.MKVAttachment` class is used to add attachments to an :class:`~pymkv.MKVFile`.
+
+Each module supports or mimics many of the same operations as mkvmerge but are not necessarily complete. If there is
+functionality that is missing or an error in the docs, please open a new issue `here <https://github
+.com/sheldonkwoodward/pymkv/issues>`_.
+
 .. toctree::
     :maxdepth: 1
 

pymkv/MKVAttachment.py

@@ -1,26 +1,61 @@
-# sheldon woodward
-# 3/28/18
+""":class:`~pymkv.MKVAttachment` classes are used to represent attachment files within an MKV or to be used in an
+MKV.
 
-"""MKVAttachment Class"""
+Examples
+--------
+Below are some basic examples of how the :class:`~pymkv.MKVAttachment` objects can be used.
+
+Create a new :class:`~pymkv.MKVAttachment` and add it to an :class:`~pymkv.MKVFile`.
+
+>>> from pymkv import MKVAttachment
+>>> attachment = MKVAttachment('path/to/attachment.jpg', name='NAME')
+>>> attachment.description = 'DESCRIPTION'
+
+Attachments can also be added directly to an :class:`~pymkv.MKVFile`.
+
+>>> from pymkv import MKVFile
+>>> mkv = MKVFile('path/to/file.mkv')
+>>> mkv.add_attachment('path/to/other/attachment.png')
+
+Now, the MKV can be muxed with both attachments.
+
+>>> mkv.add_attachment(attachment)
+>>> mkv.mux('path/to/output.mkv')
+"""
 
 from os.path import expanduser, isfile
 from mimetypes import guess_type
 
 
 class MKVAttachment:
+    """A class that represents an MKV attachment for an :class:`~pymkv.MKVFile` object.
+
+    Parameters
+    ----------
+    file_path : str
+        The path to the attachment file.
+    name : str, optional
+        The name that will be given to the attachment when muxed into a file.
+    description : str, optional
+        The description that will be given to the attachment when muxed into a file.
+    attach_once : bool, optional
+        Determines if the attachment should be added to all split files or only the first. Default is False,
+        which will attach to all files.
+
+    Attributes
+    ----------
+    mime_type : str
+        The attachment's MIME type. The type will be guessed when :attr:`~pymkv.MKVAttachment.file_path` is set.
+    name : str
+        The name that will be given to the attachment when muxed into a file.
+    description : str
+        The description that will be given to the attachment when muxed into a file.
+    attach_once : bool
+        Determines if the attachment should be added to all split files or only the first. Default is False,
+        which will attach to all files.
+    """
+
     def __init__(self, file_path, name=None, description=None, attach_once=False):
-        """A class that represents an MKV attachment.
-
-        file_path (str):
-            Path to a an attachment.
-        name (str):
-            The name of the attachment.
-        description (str):
-            The description of the attachment.
-        attach_once (bool):
-            Determines if the attachment should be added to all split files or only the first. Attach to all files is
-            default with the option as false.
-        """
         self.mime_type = None
         self._file_path = None
         self.file_path = file_path
@@ -33,6 +68,13 @@ def __repr__(self):
 
     @property
     def file_path(self):
+        """str: The path to the attachment file.
+
+        Raises
+        ------
+        FileNotFoundError
+            Raised if `file_path` does not exist.
+        """
         return self._file_path
 
     @file_path.setter