From 932153980319dcd8322d34c772d696b91acd4d8f Mon Sep 17 00:00:00 2001 From: Luke Murphy Date: Sun, 3 Nov 2019 16:44:42 +0100 Subject: [PATCH] New Sphinx theme and better docs --- CHANGELOG.rst | 17 +++++++++++++++ CONTRIBUTING.rst | 32 ++++++++++++++++++++++++++-- README.rst | 26 +++------------------- documentation/source/conf.py | 2 +- documentation/source/example.rst | 13 +++++++++++ documentation/source/index.rst | 9 ++++---- documentation/source/other-impls.rst | 8 +++++-- documentation/source/upgrade.rst | 7 ++++++ pyproject.toml | 4 ++-- setup.cfg | 1 + tox.ini | 27 ++++++++++++++++++----- 11 files changed, 107 insertions(+), 39 deletions(-) create mode 100644 documentation/source/example.rst create mode 100644 documentation/source/upgrade.rst diff --git a/CHANGELOG.rst b/CHANGELOG.rst index e69de29..3890bf8 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -0,0 +1,17 @@ +Hypercore_Crypto 0.0.1a2 (2019-11-03) +===================================== + +Improved Documentation +--------------------- + +- New Sphinx theme. +- Add a changelog. + + +Hypercore_Crypto 0.0.1a1 (2019-10-05) +===================================== + +Project Announcements +--------------------- + +- The first alpha development release is made! diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 2194e54..2b0c7b7 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -33,8 +33,36 @@ Type check source 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 19ff8d3..a9950fb 100644 --- a/README.rst +++ b/README.rst @@ -29,22 +29,11 @@ hypercore-crypto Cryptography primitives for Hypercore ------------------------------------- -Cryptography primitives for `Hypercore`_ (WIP). +Cryptography primitives for Hypercore. -.. _Hypercore: https://hypercore.readthedocs.io +Part of the `Datpy`_ project. -.. _example: - -Example -******* - -.. code-block:: python - - from hypercore_crypto import key_pair, sign, verify - - public_key, secret_key = key_pair() - signature = sign(b'hello world', secret_key) - verify(message, signature, public_key) +.. _Datpy: https://datpy.decentral1.se/ .. _documentation: @@ -54,12 +43,3 @@ Documentation * `hypercore-crypto.readthedocs.io`_ .. _hypercore-crypto.readthedocs.io: https://hypercore-crypto.readthedocs.io/ - -Mirroring -********* - -* `hack.decentral1.se/datpy/hypercore-crypto`_ -* `github.com/datpy/hypercore-crypto`_ - -.. _hack.decentral1.se/datpy/hypercore-crypto: https://hack.decentral1.se/datpy/hypercore-crypto -.. _github.com/datpy/hypercore-crypto: https://github.com/datpy/hypercore-crypto diff --git a/documentation/source/conf.py b/documentation/source/conf.py index b468f64..2ab4448 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 = 'hypercore-crypto' templates_path = ['_templates'] diff --git a/documentation/source/example.rst b/documentation/source/example.rst new file mode 100644 index 0000000..f659092 --- /dev/null +++ b/documentation/source/example.rst @@ -0,0 +1,13 @@ +.. _example: + +******* +Example +******* + +.. code-block:: python + + from hypercore_crypto import key_pair, sign, verify + + public_key, secret_key = key_pair() + signature = sign(b'hello world', secret_key) + verify(message, signature, public_key) diff --git a/documentation/source/index.rst b/documentation/source/index.rst index 19199c2..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 -***************** + :end-before: _documentation .. toctree:: + :maxdepth: 1 + :hidden: install + upgrade + example modules-api other-impls contribute diff --git a/documentation/source/other-impls.rst b/documentation/source/other-impls.rst index 3a27f79..f1424f6 100644 --- a/documentation/source/other-impls.rst +++ b/documentation/source/other-impls.rst @@ -1,7 +1,11 @@ .. _other-implementations: +********************* Other Implementations ********************* -* https://github.com/mafintosh/hypercore-crypto -* https://github.com/datcxx/hypercore-crypto +* `mafintosh/hypercore-crypto`_ +* `datcxx/hypercore-crypto`_ + +.. _mafintosh/hypercore-crypto: https://github.com/mafintosh/hypercore-crypto +.. _datcxx/hypercore-crypto: https://github.com/datcxx/hypercore-crypto diff --git a/documentation/source/upgrade.rst b/documentation/source/upgrade.rst new file mode 100644 index 0000000..e70172f --- /dev/null +++ b/documentation/source/upgrade.rst @@ -0,0 +1,7 @@ +******* +Upgrade +******* + +.. code-block:: bash + + $ pip install --upgrade hypercore-crypto diff --git a/pyproject.toml b/pyproject.toml index 0e0afe8..abed1c0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,8 +15,8 @@ include = '\.pyi?$' [tool.towncrier] directory = 'changelog/' filename = 'CHANGELOG.rst' -package = 'hypercore-crypto' -package_dir = 'hypercore-crypto' +package = 'hypercore_crypto' +package_dir = 'hypercore_crypto' [[tool.towncrier.type]] directory = 'removal' diff --git a/setup.cfg b/setup.cfg index 3f5bc4d..972e2c0 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 8bb1786..1d9cbff 100644 --- a/tox.ini +++ b/tox.ini @@ -52,20 +52,37 @@ skipdist = True 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 -extras = changelog -commands = towncrier --draft +passenv = VERSION +deps = towncrier +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