From 16d2ed16d964a5d3b1694189463d28790d9851f8 Mon Sep 17 00:00:00 2001 From: Luke Murphy Date: Sun, 3 Nov 2019 16:15:14 +0100 Subject: [PATCH] Use better docs theme and clarify docs --- CHANGELOG.rst | 10 ++++++++ CONTRIBUTING.rst | 40 +++++++++++++++++++++++++++----- README.rst | 39 ++----------------------------- documentation/source/conf.py | 2 +- documentation/source/index.rst | 7 +++--- documentation/source/upgrade.rst | 7 ++++++ setup.cfg | 1 + tox.ini | 25 ++++++++++++++++---- 8 files changed, 80 insertions(+), 51 deletions(-) create mode 100644 documentation/source/upgrade.rst diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 0633e63..8438b5d 100644 --- a/CHANGELOG.rst +++ b/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 -------- diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 2194e54..1136ddd 100644 --- a/CONTRIBUTING.rst +++ b/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 diff --git a/README.rst b/README.rst index 4cffed0..4c642b7 100644 --- a/README.rst +++ b/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 diff --git a/documentation/source/conf.py b/documentation/source/conf.py index 1098d09..82ccd62 100644 --- a/documentation/source/conf.py +++ b/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'] diff --git a/documentation/source/index.rst b/documentation/source/index.rst index 0a73afc..b3b11a7 100644 --- a/documentation/source/index.rst +++ b/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 diff --git a/documentation/source/upgrade.rst b/documentation/source/upgrade.rst new file mode 100644 index 0000000..3bdb3d7 --- /dev/null +++ b/documentation/source/upgrade.rst @@ -0,0 +1,7 @@ +******* +Upgrade +******* + +.. code-block:: bash + + $ pip install --upgrade flat-tree diff --git a/setup.cfg b/setup.cfg index 5621043..9a9e7af 100644 --- a/setup.cfg +++ b/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 diff --git a/tox.ini b/tox.ini index 5b2ca1e..9faf3af 100644 --- a/tox.ini +++ b/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