Use better docs theme and clarify docs

CHANGELOG.rst

@@ -1,6 +1,16 @@
 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
 --------
 

CONTRIBUTING.rst

@@ -10,31 +10,59 @@ Run tests
 
 .. code-block:: bash
 
-    tox -e py37
+    $ 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
+-----------------------
+
+.. code-block:: bash
+
+    $ tox -e docs
+    $ tox -e docs-livereload
+
+Make a new release
+------------------
+
+Ensure metadata for packaging is correct.
+
+.. 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
 

README.rst

@@ -43,33 +43,9 @@ From `The Dat Protocol`_:
     them uniquely efficient and convenient to implement in a wide range of
     languages.
 
-.. _example:
+Part of the `DatPy`_ project.
 
-Example
-*******
-
-.. code-block:: python
-
-    """
-
-    You can represent a binary tree in a simple
-    flat list using the following structure:
-
-           3
-       1       5
-     0   2   4   6  ...
-
-    This module exposes a series of functions
-    to help you build and maintain this data structure.
-
-    """
-
-    from flat_tree import FlatTreeAccessor
-
-    tree_access = FlatTreeAccessor()
-
-    # get array index for depth: 1, offset: 0
-    tree_access.index(1, 0)
+.. _DatPy: https://datpy.decentral1.se/
 
 .. _documentation:
 
@@ -79,14 +55,3 @@ Documentation
 * `flat-tree.readthedocs.io`_
 
 .. _flat-tree.readthedocs.io: https://flat-tree.readthedocs.io
-
-.. _mirroring:
-
-Mirroring
-*********
-
-* `hack.decentral1.se/datpy/flat-tree`_
-* `github.com/datpy/flat-tree`_
-
-.. _hack.decentral1.se/datpy/flat-tree: https://hack.decentral1.se/datpy/flat-tree
-.. _github.com/datpy/flat-tree: 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/upgrade.rst

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

setup.cfg

@@ -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

@@ -50,20 +50,37 @@ description = build the documentation
 extras = docs
 commands = python -m setup build_sphinx
 
+[testenv:docs-livereload]
+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
+passenv = VERSION
 deps = towncrier
-commands = towncrier --draft
+commands = towncrier --version={env:VERSION} {posargs}
 
 [testenv:metadata-release]
 description = validate the package metadata
 deps = twine
-commands = twine check {toxworkdir}/dist/*
+commands = 
+  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 = {[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