This is the starting point of documenting Hyde using Sphinx. This
provides several benefits:
1. Code and documentation live together, so it's easier to track and
enforce that there exists documentation for new or changing code.
2. This lets us get Hyde on Read The Docs.
3. We can use things like `autoclass` where appropriate to pull
documentation directly from source code without reinventing the wheel.
I've tried to replicate what currently exists on hyde.github.io. The
first pass of this effort is concerned with parity, and we can continue
to improve from there on. Steps:
1. Convert all existing documentation on hyde.github.io to Sphinx. This
is covered by this commit and should be considered "in review".
2. Open issues for core parts of Hyde that are missing documentation.
3. Close these issues individually. This is a great opportunity for
community members wishing to get involved to contribute.
4. Require significant changes in code to be accompanied by updated /
new documentation the same way we would require tests.
While these steps are in progress, the following should also be done:
1. Deprecate the docs at hyde.github.io, linking users to Read The Docs.
2. Replace the content currently hosted at hyde.github.io with a new
brochure site showing off some of Hyde's uses and linking to other
interesting content (e.g. a list of themes, links to sites powered by
Hyde, etc.).
References #188, #209, and quite a few other issues.
@lakshmivyas, @llonchj: please review. This is a starting point for
Sphinx docs, and the PR is labelled as a work in progress, but I have no
specific threshold for it being "done". Once we're all satisfied with
the first pass, I'll set up RTD, and we can start filing issues for
specific areas lacking docs.
All tests* currently pass under Python 2.7 and Python 3.3 - 3.5. This
does not mean that Python 3 support is stable, however. As a plan
forward, we should encourage interested users to run Hyde with Python 3,
report bugs, and submit patches. This change references the Python 3
Support issue on GitHub (#270). Once this becomes a bit more tested and
stable, that issue should be closed, and Hyde should announce official,
stable support for Python 3 (i.e. new changes must also support 3,
issues with running hyde under 3 should be considered bugs rather than
feature requests, etc.).
Changes:
- Add ``hyde/_compat.py`` for 2-to-3 compatibility helpers.
- Replace uses of 2-specific code with their ``hyde._compat`` versions.
- Tests remain largely unchanged (for good reason). The exceptions here
are to ``print`` function calls, and ``str`` type usage, and
compatibility imports.
- Replace explicit calls to ``foo.next()`` with ``next(foo)``. This
keeps code portable between Python 2's ``next`` and Python 3's
``__next__`` methods without the need for any compatibility functions
and is the recommended API for interacting with these methods.
- Replace deprecated (and, in Python 3, removed) ``except Exception, e:``
statements with their updated ``except Exception as e:`` versions.
- Replace print statements with print function calls (because of how
parentheses work in Python, this is transparently
cross-version-compatible).
- Add Python 3.3, 3.4, and 3.5 to ``tox.ini``, ``.travis.yml``, and
classifiers in ``setup.py``.
- Add ``{posargs}`` to ``tox.ini`` command invocations to improve usage
during development.
- Add Python 3 note in changelog.
* asciidoc does not support Python 3, and fixing that far beyond the
scope of this task, so the test that deals with it is conditionally
skipped when run using versions of Python 3.