Use better docs theme and clarify docs

Cleanups on package meta and docs

.travis.yml

@@ -0,0 +1,26 @@
+language: python
+
+matrix:
+  include:
+    - python: 3.6
+      env: TOXENV=py36
+    - python: 3.7
+      env: TOXENV=py37
+    - python: 3.7
+      env: TOXENV=lint
+    - python: 3.7
+      env: TOXENV=sort
+    - python: 3.7
+      env: TOXENV=format
+    - python: 3.7
+      env: TOXENV=type
+    - python: 3.7
+      env: TOXENV=docs
+    - python: 3.7
+      env: TOXENV=metadata-release
+
+install:
+  - pip install tox==3.13.2
+
+script:
+  - tox -v

CHANGELOG.rst

@@ -1,10 +1,20 @@
 Flat_Tree 0.0.1a3 (2019-07-01)
 ==============================
 
+Improved Documentation
+--------
+
+- Use the sphinx_rtd_theme.
+- Attempt to clarify sections using better navigation.
+
+
+Flat_Tree 0.0.1a3 (2019-07-01)
+==============================
+
 Removals
 --------
 
-- Don't advertise Python 3.5 which is not supported. (#1)
+- Don't advertise Python 3.5 which is not supported.
 
 
 Flat_Tree 0.0.1a2 (2019-07-01)
@@ -13,4 +23,4 @@ Flat_Tree 0.0.1a2 (2019-07-01)
 Project Announcements
 ---------------------
 
-- Initial development release is made! (#1)
+- The first alpha development release is made!

CONTRIBUTING.rst

@@ -1,67 +1,69 @@
 Get started
 -----------
 
-Install `Tox`_ with:
+Install `Tox`_.
 
 .. _tox: http://tox.readthedocs.io/
 
-.. code-block:: bash
-
-    $ pip install --user tox
-
 Run tests
 ---------
 
 .. code-block:: bash
 
-    tox -e test
+    $ tox -e py37
 
 Lint source
 -----------
 
 .. code-block:: bash
 
-    tox -e lint
+    $ tox -e lint
 
 Format source
 -------------
 
 .. code-block:: bash
 
-    tox -e format
+    $ tox -e format
 
 Type check source
 -----------------
 
 .. code-block:: bash
 
-    tox -e type
+    $ tox -e type
 
-Release Process
+Build the documentation
----------------
+-----------------------
-
-Add a change entry and re-generate the changelog:
 
 .. code-block:: bash
 
-    $ towncrier
+    $ tox -e docs
+    $ tox -e docs-livereload
 
-Make a new release tag:
+Make a new release
+------------------
 
-.. code-block:: bash
+Ensure metadata for packaging is correct.
-
-    $ git tag x.x.x
-    $ git push --tags
-
-If you have a development install locally, you can verify:
-
-.. code-block:: bash
-
-    $ flat_tree --version
-
-Then run the release process:
 
 .. code-block:: bash
 
     $ tox -e metadata-release
+
+Generate the changelog with the next target version.
+
+.. code-block:: bash
+
+    $ export VERSION=1.0.1 tox -e changelog
+
+Make a new Git tag.
+
+.. code-block:: bash
+
+    $ git tag  -a 1.0.1
+
+And finally, make a new release.
+
+.. code-block:: bash
+
     $ tox -e release

FUNDING.yml

@@ -0,0 +1 @@
+liberapay: decentral1se

README.rst

@@ -8,10 +8,14 @@ flat-tree
    :target: LICENSE
    :alt: Repository license
 
-.. image:: https://badge.fury.io/py/flat_tree.svg
+.. image:: https://badge.fury.io/py/flat-tree.svg
-   :target: https://badge.fury.io/py/flat_tree
+   :target: https://badge.fury.io/py/flat-tree
    :alt: PyPI Package
 
+.. image:: https://travis-ci.com/datpy/flat-tree.svg?branch=master
+   :target: https://travis-ci.com/datpy/flat-tree
+   :alt: Travis CI result
+
 .. image:: https://readthedocs.org/projects/flat-tree/badge/?version=latest
    :target: https://flat-tree.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status
@@ -39,17 +43,15 @@ From `The Dat Protocol`_:
     them uniquely efficient and convenient to implement in a wide range of
     languages.
 
+Part of the `DatPy`_ project.
+
+.. _DatPy: https://datpy.decentral1.se/
+
 .. _documentation:
 
 Documentation
 *************
 
-* https://flat-tree.readthedocs.io
+* `flat-tree.readthedocs.io`_
 
-.. _mirroring:
+.. _flat-tree.readthedocs.io: https://flat-tree.readthedocs.io
-
-Mirroring
-*********
-
-* https://hack.decentral1.se/datpy/flat_tree (primary)
-* https://github.com/datpy/flat_tree

documentation/source/conf.py

@@ -1,7 +1,7 @@
 author = 'decentral1se'
 copyright = '2019, decentral1se'
 html_static_path = ['_static']
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 master_doc = 'index'
 project = 'flat-tree'
 templates_path = ['_templates']

documentation/source/index.rst

@@ -1,12 +1,13 @@
 .. include:: ../../README.rst
    :end-before: _documentation
 
-Table of Contents
-*****************
-
 .. toctree::
+   :maxdepth: 1
+   :hidden:
 
    install
+   upgrade
+   example
    modules-api
    other-impls
    contribute

documentation/source/modules-api.rst

@@ -1,3 +1,5 @@
+.. _modules_api:
+
 ***********
 Modules API
 ***********

documentation/source/other-impls.rst

@@ -3,7 +3,12 @@
 Other Implementations
 *********************
 
-* https://github.com/mafintosh/flat-tree
+* `mafintosh/flat-tree`_
-* https://github.com/datrs/flat-tree
+* `datrs/flat-tree`_
-* https://github.com/bcomnes/flattree
+* `bcomnes/flattree`_
-* https://github.com/datcxx/flat-tree
+* `datcxx/flat-tree`_
+
+.. _mafintosh/flat-tree: https://github.com/mafintosh/flat-tree
+.. _datrs/flat-tree: https://github.com/datrs/flat-tree
+.. _bcomnes/flattree: https://github.com/bcomnes/flattree
+.. _datcxx/flat-tree: https://github.com/datcxx/flat-tree

documentation/source/upgrade.rst

@@ -0,0 +1,7 @@
+*******
+Upgrade
+*******
+
+.. code-block:: bash
+
+    $ pip install --upgrade flat-tree

flat_tree/iterator.py

@@ -19,6 +19,10 @@ class FlatTreeIterator:
     def __attrs_post_init__(self):
         self.seek(self.index)
 
+    # TODO(decentral1se): Once we get to the point of actually using this
+    # module in hypercore or wherever it is needed we should consider whether
+    # or not to make this a real Python iterator using the protocol methods of
+    # __iter__ and __next__
     def next(self) -> int:
         """The next index in the tree."""
         self.offset += 1

setup.cfg

@@ -35,7 +35,7 @@ classifiers =
 
 [options]
 use_scm_version = True
-python_requires = !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5
+python_requires = >=3.6
 setup_requires =
   setuptools_scm
   setuptools_scm_git_archive
@@ -58,6 +58,7 @@ warning-is-error = True
 [options.extras_require]
 docs =
   sphinx
+  sphinx_rtd_theme
   sphinx-autodoc-typehints >= 1.6.0, < 2.0
 changelog =
   towncrier <= 19.2.0, < 20.0

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 envlist =
-    {py36,py37}-test
+    {py36,py37}
     lint
     sort
     format
@@ -17,70 +17,70 @@ deps =
   pytest
   pytest-cov
   pytest-mock
-commands = 
+commands = pytest test/ --cov={toxinidir}/flat_tree/ --no-cov-on-fail {posargs}
-  pytest test/ --cov={toxinidir}/flat_tree/ --no-cov-on-fail {posargs}
 
 [testenv:lint]
 description = lint the source
 skipdist = True
-deps = 
+deps = flake8
-  flake8
+commands = flake8 {posargs} flat_tree/ test/
-commands = 
-  flake8 {posargs} flat_tree/ test/
 
 [testenv:sort]
 description = sort the source
 skipdist = True
-deps = 
+deps = isort
-  isort
+commands = isort {posargs:-rc -c} -sp setup.cfg flat_tree/ test/
-commands = 
-  isort {posargs:-rc -c} -sp setup.cfg flat_tree/ test/
 
 [testenv:format]
 description = format the source
 skipdist = True
 basepython = python3.6
-deps = 
+deps = black
-  black
+commands = black {posargs:--check} flat_tree/ test/
-commands = 
-  black {posargs:--check} flat_tree/ test/
 
 [testenv:type]
 description = type check the source
 basepython = python3.7
 skipdist = True
-deps = 
+deps = mypy
-  mypy
+commands = mypy flat_tree/ test/
-commands = 
-  mypy flat_tree/ test/
 
 [testenv:docs]
 description = build the documentation
-deps = 
+extras = docs
-  sphinx
+commands = python -m setup build_sphinx
-  sphinx-autodoc-typehints >= 1.6.0, < 2.0
+
-commands = 
+[testenv:docs-livereload]
-  python -m setup build_sphinx
+description = invoke sphinx-autobuild to build and reload the documentation
+commands = python -m sphinx_autobuild documentation/source documentation/build
+deps = sphinx-autobuild>=0.7.1,<1.0
+extras = docs
 
 [testenv:changelog]
-description = draft the changelog
+description = draw up the new changelog
 skipdist = True
-deps = 
+passenv = VERSION
-  towncrier
+deps = towncrier
-commands = 
+commands = towncrier --version={env:VERSION} {posargs}
-  towncrier --draft
 
 [testenv:metadata-release]
 description = validate the package metadata
-deps =
+deps = twine
-  twine
 commands = 
-  twine check .tox/dist/*
+  rm -rf {toxworkdir}/dist
+  python -m setup sdist --dist-dir {toxworkdir}/dist bdist_wheel
+  python -m setup sdist --dist-dir {toxworkdir}/dist bdist_egg
+  twine check {toxworkdir}/dist/*
+whitelist_externals =
+    rm
 
 [testenv:release]
 description = make a release
-deps =
+deps = {[testenv:metadata-release]deps}
-  {[testenv:metadata-release]deps}
 commands =
-    python -m setup sdist bdist_wheel
+    rm -rf {toxworkdir}/dist
+    python -m setup sdist --dist-dir {toxworkdir}/dist bdist_wheel
+    python -m setup sdist --dist-dir {toxworkdir}/dist bdist_egg
     twine upload {toxworkdir}/dist/*
+whitelist_externals =
+    rm