Skip to content

Commit

Permalink
Moved documentation to Sphinx/Readthedocs
Browse files Browse the repository at this point in the history
  • Loading branch information
sg495 committed Dec 30, 2021
1 parent 3ed5cbf commit 28ed1d1
Show file tree
Hide file tree
Showing 64 changed files with 1,952 additions and 11,399 deletions.
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -127,3 +127,6 @@ dmypy.json

# Pyre type checker
.pyre/

# local README proof from readme_renderer
README-PROOF.html
10 changes: 5 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,12 +77,12 @@ Whenever relevant, please consider contributing some additional tests pertaining

### Documentation

The API documentation for this project is generated automatically by [pdoc](https://pdoc3.github.io/pdoc/):
The API documentation for this project is generated by [Sphinx](https://www.sphinx-doc.org/): please document any code changes and additions using [reST](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) docstrings. The documentation is generated by running the following commands in the [docs/](docs/) folder:

```
pdoc --config latex_math=True --config show_type_annotations=True --force --html --output-dir docs bases
docs>make api
docs>make clean
docs>make html
```

If you write new functions, classes or modules, please consider documenting them using Markdown docstrings, in pdoc's format.

If you edit the [readme page](README.md), please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification.
The script `make-api-clean-html.bat` automates the procedure on Windows. If you edit the [readme page](README.rst), please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification.
120 changes: 0 additions & 120 deletions README.md

This file was deleted.

144 changes: 144 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
bases: A Python library for Base-N encodings
============================================

.. image:: https://img.shields.io/badge/python-3.7+-green.svg
:target: https://docs.python.org/3.7/
:alt: Python versions

.. image:: https://img.shields.io/pypi/v/bases.svg
:target: https://pypi.python.org/pypi/bases/
:alt: PyPI version

.. image:: https://img.shields.io/pypi/status/bases.svg
:target: https://pypi.python.org/pypi/bases/
:alt: PyPI status

.. image:: http://www.mypy-lang.org/static/mypy_badge.svg
:target: https://github.com/python/mypy
:alt: Checked with Mypy

.. image:: https://readthedocs.org/projects/bases/badge/?version=latest
:target: https://bases.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status

.. image:: https://github.com/hashberg-io/bases/actions/workflows/python-pytest.yml/badge.svg
:target: https://github.com/hashberg-io/bases/actions/workflows/python-pytest.yml
:alt: Python package status

.. image:: https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square
:target: https://github.com/RichardLitt/standard-readme
:alt: standard-readme compliant


Bases provides a customisable, parametric implementation of several common styles of Base-N encoding, covering all cases appearing in the `multibase specification <https://github.com/multiformats/multibase>`_ (except for proquints).


.. contents::


Install
-------

You can install the latest release from `PyPI <https://pypi.org/project/bases/>`_ as follows:

.. code-block:: console
$ pip install --upgrade bases
Usage
-----

We suggest you import bases as follows:

>>> import bases


Below are some basic usage examples, to get you started: for detailed documentation, see https://bases.readthedocs.io/


Base encoding objects
^^^^^^^^^^^^^^^^^^^^^

>>> from bases import base32
>>> base32
FixcharBaseEncoding(
StringAlphabet('ABCDEFGHIJKLMNOPQRSTUVWXYZ234567',
case_sensitive=False),
pad_char='=', padding='include')


Encoding
^^^^^^^^

>>> b = bytes([70, 98, 190, 187, 66, 224, 178])
>>> base32.encode(b)
'IZRL5O2C4CZA===='


Decoding
^^^^^^^^

>>> s = 'IZRL5O2C4CZA===='
>>> base32.decode(s)
b'Fb\xbe\xbbB\xe0\xb2'
>>> list(base32.decode(s))
[70, 98, 190, 187, 66, 224, 178]


Case/padding variations
^^^^^^^^^^^^^^^^^^^^^^^

>>> b = bytes([70, 98, 190, 187, 66, 224, 178])
>>> base32.encode(b)
'IZRL5O2C4CZA===='
>>> base32lower = base32.lower()
>>> base32lower
FixcharBaseEncoding(
StringAlphabet('abcdefghijklmnopqrstuvwxyz234567',
case_sensitive=False),
pad_char='=', padding='include')
>>> base32lower.encode(b)
'izrl5o2c4cza===='
>>> base32nopad = base32.nopad()
>>> base32nopad.encode(b)
'IZRL5O2C4CZA'


Case sensitivity variations
^^^^^^^^^^^^^^^^^^^^^^^^^^^

>>> s = 'IZRL5O2C4CZA===='
>>> base32lower.decode(s)
b'Fb\xbe\xbbB\xe0\xb2'
>>> base32lower_casesensitive = base32lower.with_case_sensitivity(True)
>>> base32lower_casesensitive.decode(s)
bases.encoding.errors.NonAlphabeticCharError: Invalid character 'I'
encountered for alphabet StringAlphabet('abcdefghijklmnopqrstuvwxyz234567').


Custom base encodings
^^^^^^^^^^^^^^^^^^^^^

>>> base4 = bases.make("0123", kind="zeropad-enc", block_nchars=4)
>>> base4
ZeropadBaseEncoding(StringAlphabet('0123'), block_nchars=4)



API
---

For the full API documentation, see https://bases.readthedocs.io/


Contributing
------------

Please see `<CONTRIBUTING.md>`_.


License
-------

`MIT © Hashberg Ltd. <LICENSE>`_
44 changes: 0 additions & 44 deletions _setup.py

This file was deleted.

Loading

0 comments on commit 28ed1d1

Please sign in to comment.