Commits

Travis Shirk committed 46ef928

docs cleanup and progress.

Comments (0)

Files changed (22)

 *.pyc
 *.swp
 build/*
-docs/.build/*
+docs/_build/*
 .coverage
 src/eyed3/info.py
 tags
 
 Python 2.7 is required.
 
-The easiest way to install eyeD3 is to use ``pip``::
-
-  $ pip install eyeD3
-
-.. note::
-  This may require root access.
-
-For alternate installation instructions and more complete documentation see
+For `installation instructions`_ or more complete `documentation`_ see
 http://eyeD3.nicfit.net/
 
-Post feedback and/or defects on the `issue tracker`_, or `mailing list`_.
+Please post feedback and/or defects on the `issue tracker`_, or `mailing list`_.
 
 .. _eyeD3: http://eyeD3.nicfit.net/
 .. _Travis Shirk: travis@pobox.com
 .. _issue tracker: https://bitbucket.org/nicfit/eyed3/issues?status=new&status=open
 .. _mailing list: https://groups.google.com/forum/?fromgroups#!forum/eyed3-users
-.. _GPL: https://bitbucket.org/nicfit/eyed3/raw/6dfa97d26479/COPYING
+.. _installation instructions: http://eyeD3.nicfit.net/index.html#installation
+.. _documentation: http://eyeD3.nicfit.net/index.html#documentation
+.. _GPL: http://www.gnu.org/licenses/gpl-2.0.html
 .. _ID3: http://id3.org/
 
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = .build
+BUILDDIR      = _build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4

docs/_static/.keepme

Empty file removed.

docs/api.rst

-
-API Reference
--------------
-
-.. toctree::
-
-   eyed3
-   eyed3.core
+============
+eyeD3 Module
+============
+
+.. automodule:: eyed3
+    :members:
+    :undoc-members:
+================
+eyed3.id3 Module
+================
+
+.. automodule:: eyed3.id3
+    :members:
+    :undoc-members:
+
+.. automodule:: eyed3.id3.tag
+    :members:
+    :undoc-members:
+
+
+================
+eyed3.mp3 Module
+================
+
+.. automodule:: eyed3.mp3
+    :members:
+    :undoc-members:
+================
+eyed3.plugins Module
+================
+
+.. automodule:: eyed3.plugins
+    :members:
+    :undoc-members:
+
+================
+eyed3.utils Module
+================
+
+.. automodule:: eyed3.utils
+    :members:
+    :undoc-members:
 
-###############
-Release History
-###############
+#########
+ChangeLog
+#########
 
 **0.7.0** - TDB (TBD)
 
       lame (xing) header information.
     * Module name is now ``eyed3`` (all lower case) to be more standards
       conforming.
-    * New ``Tag`` interface based on properties.
+    * New ``eyed3.id3.Tag`` interface based on properties.
     * Improved ID3 date frame support and 2.3<->2.4 conversion, and better
       conversions, in general.
     * Python Package Index friendly, and installable with 'pip'.
     * Improved mime-type detection.
     * Improved unicode support.
-    * Support for config files to contain common options.
+    * Support for config files to contain common options for the command-line
+      tool.
 
 **0.6.18** - 11.25.2011 (Nobunny loves you)
   New features:
 
 Configuration Files
 -------------------
+TODO
 
 Custom Plugins
 --------------
+TODO
 
-FIXME:
-Plugins can be written in Python by implementing ``eyed3.plugins.Plugin``
-and class and putt a module (i.e. .py)
-in the search path (FIXME: what's the path).
-
-.. autoclass:: eyed3.plugins.Plugin
-   :members:

docs/compliance.rst

-##########
-Compliance
-##########
-
-
-ID3
-===
-
-Unsupported Features
---------------------
-* ID3 frame encryption
-* Writing of sync-safe data (i.e. unsynchronized), because it is 2012.
-  Reading of unsyncronized tags (v2.3) and frames (v2.4) **is** supported.
-
-Dates
------
-
-ID3 v2.3 Date Frames
-~~~~~~~~~~~~~~~~~~~~
-- TDAT date (recording date of form DDMM, always 4 bytes)
-- TYER year (recording year of form NNNN, always 4 bytes)
-- TIME time (recoding time of form HHMM, always 4 bytes)
-- TORY orig release year
-- TRDA recording date (more freeform replacement for TDAT, TYER, TIME.
-  e.g., "4th-7th June, 12th June" in combination with TYER)
-
-ID3 v2.4 Date Frames
-~~~~~~~~~~~~~~~~~~~~
-- TDEN encoding datetime
-- TDOR orig release date
-- TDRC recording date
-- TDRL release date
-- TDTG tagging time
-
-The timestamp fields are based on a subset of ISO 8601. When being as
-precise as possible the format of a time string is:
-
-yyyy-MM-ddTHH:mm:ss (year, "-", month, "-", day, "T", hour (out of
-24), ":", minutes, ":", seconds), but the precision may be reduced by
-removing as many time indicators as wanted. Hence valid timestamps
-are yyyy, yyyy-MM, yyyy-MM-dd, yyyy-MM-ddTHH, yyyy-MM-ddTHH:mm
-and yyyy-MM-ddTHH:mm:ss. All time stamps are UTC. For
-durations, use the slash character as described in 8601, and for
-multiple non- contiguous dates, use multiple strings, if allowed
-by the frame definition.
-
-The ISO 8601 'W' delimiter for numeric weeks is NOT supported.
-
-Common Date Frames
-~~~~~~~~~~~~~~~~~~
-TDLY playlist delay (2.3 and 2.4 - number of millisecond delay between playlist
-tracks)
-
-
-v2.4 <-> 2.3 mappings
-~~~~~~~~~~~~~~~~~~~~~
-When converting to/from v2.3 and v2.4 it is neceswsary to convert date frames.
-The following is the mappings eyeD3 uses when converting.::
-
-  TDEN -> None
-  TDOR <-> TORY (year only)
-  TDRC <-> TIME (HHmm), TDAT (DDMM), TYER
-  TDRL <-> None
-  TDTG -> None
-
-
-Non Standard Frame Support
---------------------------
-
-NCON
-~~~~
-A MusicMatch extension of unknown binary format. Frames of this type are
-parsed as raw ``Frame`` objects, therefore the data is not parsed. The frames
-are preserved and can be deleted and written (as is).
-
-TCMP
-~~~~
-An iTunes extension to signify that a track is part of a compilation.
-This frame is handled by ``TextFrame`` and the data is either a '1' if
-part of a compilation or '0' (or empty) if not.
-
-XSOA, XSOP, XSOT
-~~~~~~~~~~~~~~~~
-These are alternative sort-order strings for album, performer, and title,
-respectively. They are often added to ID3v2.3 tags while v2.4 does not
-require them since TSOA, TSOP, and TSOT are native frames.
-
-These frames are preserved but are not written when using v2.3. If the
-tag is converted to v2.4 then the corresponding native frame is used.
-
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['.build']
+exclude_patterns = ['_build']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {"nosidebar": True}
+html_theme_options = {"nosidebar": False}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []

docs/eyed3.core.rst

-:mod:`eyed3.core`
-=================
-
-.. automodule:: eyed3.core
-
-.. autofunction:: eyed3.core.load
-
-.. autoclass:: eyed3.core.AudioFile
-   :members:
-   :private-members: _read
-
-.. autoclass:: eyed3.core.AudioInfo
-   :members:
-
-.. autoclass:: eyed3.core.Tag
-   :members:

docs/eyed3.rst

-:mod:`eyed3`
-============
-
-.. autofunction:: eyed3.require
-
-.. code-block:: python
-
-  try:
-      eyed3.require("0.7")
-  except eyed3.Exception as ex:
-      sys.stderr.write(str(ex))
-      sys.exit(1)
-
-.. autofunction:: eyed3.core.load
-
-.. code-block:: python
-
-  import eyed3
-  audio_file = eyed3.load("example.mp3")
-  audio_file = eyed3.load("sample.id3")
-
-The character encoding of the OS and file system are detected and used for 
-byte string conversions of file names, command line arguments, and console
-output. Note, the values right of the '=' sign below are computed values
-(on the document server) and **NOT** the default values.
-
-.. autodata:: eyed3.LOCAL_ENCODING
-.. autodata:: eyed3.LOCAL_FS_ENCODING
-
-.. autoclass:: eyed3.Exception
-   :members:
-   :inherited-members:
-
-.. eyeD3 documentation master file, created by
-   sphinx-quickstart on Mon Feb  6 19:56:45 2012.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-===============
-eyeD3 |version|
-===============
+=====
+eyeD3
+=====
 
 .. include:: ../README.rst
 
-Examples
-========
+Installation
+============
 
-Modify the artist, album, title, and track number of ``example.mp3`` in the
-console:
+Stable releases of eyeD3 are best installed via ``pip`` or ``easy_install``;
+or you may download TGZ or ZIP source archives from a couple of official
+locations. Detailed instructions and links may be found on the
+:doc:`installation` page.
 
-.. code-block:: bash
+Otherwise, if you want to live on the edge, you can pull down the source code
+from the Mercurial repository at `Bit Bucket`_. The :doc:`installation` page has
+details for how to access the source code.
 
-  $ eyeD3 --artist=Nobunny --album="Love Visions" --title="I Am a Girlfried"
-          --track=4 example.mp3
+.. _Bit Bucket: https://bitbucket.org/nicfit/eyed3
 
+.. toctree::
+    :hidden:
+    
+    installation
 
-Or use Python...
-
-.. code-block:: python
-
-  import eyed3
-
-  audiofile = eyed3.load("example.mp3")
-  audiofile.tag.artist = u"Nobunny"
-  audiofile.tag.album = u"Love Visions"
-  audiofile.tag.title = u"I Am a Girlfried"
-  audiofile.tag.track_num = 4
-
-  audiofile.tag.save()
+.. _documentation-index:
 
 Documentation
 =============
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
 
-   install
-   cli
-   api
-   compliance
-   changelog
-   license
+    cli
+    changelog
+
+.. _api-index:
+
+API
+===
+
+.. toctree::
+
+    api/eyed3.rst
+    api/id3.rst
+    api/mp3.rst
+    api/plugins.rst
+    api/utils.rst
+
+
+ChangeLog
+=========
+
+Changes made to eyeD3 and the project's release history can be found in the
+:doc:`changelog`.
+
+.. _references-index:
 
 References
 ==========
 - ISO `639-2 Language Codes <http://en.wikipedia.org/wiki/ISO_639-2>`_
 - MusicBrainz Tag `Mappings <http://wiki.musicbrainz.org/MusicBrainz_Tag>`_
 
+
 Indices and tables
 ==================
 

docs/install.rst

-
-Installation
-============
-.. note::
-  The latest stable release is eyeD3 |latest_stable_version|.
-
-Prerequisites
--------------
-eyeD3 |version| (|release|) has been tested with Python 2.7.
-
-Optional
-~~~~~~~~
-* For better mime-type identification install `python-magic`_
-
-Install using 'pip'
--------------------
-*pip* is a tool for installing Python packages from `Python Package Index`_ and
-is a replacement for *easy_install*. It will install the package using the
-first 'python' in your path so it is especially useful when used along with 
-`virtualenv`_, otherwise root access may be required.
-
-.. code-block:: sh
-
-    $ pip install eyeD3
-    $ pip install python-magic  # optional
-
-Install From Source
--------------------
-Source packages can be downloaded from `here`_:
-
-.. code-block:: sh
-
-    $ tar xzf eyeD3-0.7.0-final.tar.gz
-    $ cd eyeD3-0.7.0-final
-    $ ./configure
-    $ make install
-
-.. _here: http://eyed3.nicfit.net/releases/
-
-Cloning The Repository
-----------------------
-.. code-block:: sh
-
-    $ hg clone https://nicfit@bitbucket.org/nicfit/eyed3
-    $ cd eyed3
-    $ ./autogen.sh
-
-To setup a development environment with all the necessary development tools
-use the ``mkenv.bash`` script.
-
-.. note::
- The ``mkenv.bash`` script requires `virtualenvwrapper`_. Users of
- ``virtualenv`` directly (without the wrapper) should consult the script to
- guide the setup of a virtual development environment.
-
-.. code-block:: sh
-
-    $ ./mkenv.bash
-    $ workon eyeD3
-    $ make test
-
-
-.. _virtualenv: http://www.virtualenv.org/
-.. _virtualenvwrapper: http://www.doughellmann.com/projects/virtualenvwrapper
-.. _Python Package Index: http://pypi.python.org/pypi/eyeD3
-.. _python-magic: https://github.com/ahupp/python-magic

docs/installation.rst

+============
+Installation
+============
+
+Easy Installation
+=================
+
+Install using 'pip'
+-------------------
+*pip* is a tool for installing Python packages from `Python Package Index`_ and
+is a replacement for *easy_install*. It will install the package using the
+first 'python' in your path so it is especially useful when used along with 
+`virtualenv`_, otherwise root access may be required.
+
+.. code-block:: sh
+
+    $ pip install eyeD3
+    $ pip install python-magic  # optional
+
+.. _virtualenv: http://www.virtualenv.org/
+.. _Python Package Index: http://pypi.python.org/pypi/eyeD3
+
+Dependencies
+============
+eyeD3 |version| has been tested with Python 2.7. Currently it is the only supported version of
+Python. Support for older versions has been ruled out since 2.7 version provides the best migration
+path to supporting Python3.
+
+The primary interface for building and installing is `Setuptools`_. For example,
+``python setup.py install``. This is an illusion though, ``setuptools`` is *NOT* required because
+`Paver`_ is used instead and it provides the common ``setup.py`` interface that everyone knows
+and loves. In addition, ``Paver`` itself is not required for building/installing, only when
+doing development on eyeD3 itself.
+
+eyeD3 has NO hard dependencies other thant Python itself but it may take advantage of other
+packages if they are available.
+
+.. _setuptools: http://pypi.python.org/pypi/setuptools
+.. _Paver: http://paver.github.com/paver/
+
+Optional Dependencies
+---------------------
+
+* `python-magic`_: If this package is installed (or the older ``magic.py`` that often ships with
+  libmagic) it will be used to do better file mime-type detection.
+
+.. _python-magic: https://github.com/ahupp/python-magic
+
+Development Dependencies
+------------------------
+
+If you are interested in doing development work on eyeD3 (or even just running
+the test suite), you may also need to install some or all of the following
+packages:
+
+* `Nose <http://code.google.com/p/python-nose/>`_
+* `Coverage <http://nedbatchelder.com/code/modules/coverage.html>`_
+* `Sphinx <http://sphinx.pocoo.org/>`_
+
+For an up-to-date list of exact testing/development requirements, including
+version numbers, please see the ``dev-requirements.txt`` file included with the
+source distribution. This file is intended to be used with ``pip``, e.g. ``pip
+install -r dev-requirements.txt``.
+
+Download Source Archive
+=======================
+
+Source packages are available from the `release archive`_ in tgz and zip formats.
+After unarchiving the distribution file you can install in the common manner:
+
+.. code-block:: sh
+
+    $ tar xzf eyeD3-X.Y.Z-final.tgz
+    $ cd eyeD3-X.Y.Z-final
+    # This may require root access
+    $ python setup.py install
+
+Or you can run from the archive directory directly:
+
+.. code-block:: sh
+
+    $ tar xzf eyeD3-X.Y.Z-final.tgz
+    $ cd eyeD3-X.Y.Z-final
+    $ python setup.py build
+    $ export PTHONPATH=`pwd`/build/lib
+    $ export PATH=${PATH}:`pwd`/bin
+
+.. _release archive: http://eyed3.nicfit.net/releases/
+
+Checking Out the Source Code
+============================
+
+The eyeD3 project is managed with `Mercurial
+<http://mercurial.selenic.com/wiki/>`_. To follow eyeD3's development via
+Mercurual instead of downloading official releases, you have the following
+options from the `eyeD3 BitBucket page`_.
+
+* Clone the repository using ``hg`` and the clone URL provided.
+* Make your own fork of the eyeD3 repository by logging into BitBucket and clicking the ``Fork``
+  button on the `eyeD3 BitBucket page`_.
+
+To clone the repository to your computer, for instance:
+
+.. code-block:: sh
+
+    $ hg clone https://nicfit@bitbucket.org/nicfit/eyed3
+    $ cd eyed3
+    # To work on the stable branch
+    $ hg update stable
+    # Otherwise you are on the 'default' branch.
+
+.. note::
+  When submitting patches please base them on the 'stable' branch.
+
+It is recommended that you work on eyeD3 within a virtual Python environment since it allows you
+to install the required tools without root access and without clobbering your system installation
+of Python. The top-level directory makes this very easy if you have `virtualenvwrapper`_ installed.
+
+.. code-block:: sh
+
+    $ ./mkenv.bash
+    $ workon eyeD3
+    $ paver test
+
+In the above command a virtual enviroment called `eyeD3` was created and all of the necessary
+developer tools were installed. We then "switch" to this new environment with ``workon`` and
+run the eyeD3 unit tests using ``paver``. The last call to `Paver`_ will run from the virtual
+enviroment, as will the ``Nose`` library that the unit tests require.
+
+.. note::
+  The ``mkenv.bash`` script requires `virtualenvwrapper`_. It provides a nice interface around
+  ``virtualenv`` including the easy switching of environments via the ``workon`` command. If you
+  do not wish to install the wrapper you can use ``virtualenv`` directly but may wish to consult
+  the script for the required steps.
+
+.. _eyeD3 BitBucket page: https://bitbucket.org/nicfit/eyed3
+.. _virtualenvwrapper: http://www.doughellmann.com/projects/virtualenvwrapper

docs/license.rst

-License
-=======
-
-.. include:: ../COPYING
-   :literal:
     put("./dist/%s.md5" % os.path.splitext(SRC_DIST_TGZ)[0], RELEASE_D)
 
 def deploy_docs():
+    raise NotImplementedError("FIXME: disabled until I know I won't blow away the 0.6 files")
     put("./dist/%s" % DOC_DIST, "~")
     run("tar xzf eyeD3_docs-0.7.0-rc1.tgz -C ./www/eyeD3 --strip-components=1")
 
 SRC_DIST_ZIP = "%s.zip" % os.path.splitext(SRC_DIST_TGZ)[0]
 DOC_DIST = "%s_docs-%s.tgz" % (PROJECT, VERSION)
 MD5_DIST = "%s.md5" % os.path.splitext(SRC_DIST_TGZ)[0]
-DOC_BUILD_D = "docs/.build"
+DOC_BUILD_D = "docs/_build"
 
 PACKAGE_DATA = paver.setuputils.find_package_data("src/eyed3",
                                                   package="eyed3",