update docs

README.md

@@ -21,12 +21,13 @@ added to the list being as visually distinct from the pre-existing colours in
 
 *distinctipy* is designed for Python 3 and can be installed with pip by running:
 
-```python
+```shell
 pip install distinctipy
 ```
 
 Alternatively clone the repo and install it locally:
-```bash
+
+```shell
 git clone https://github.com/alan-turing-institute/distinctipy.git
 cd distinctipy
 pip install .
@@ -91,6 +92,6 @@ stack overflow answers. In particular:
 * **Best text colour for background:** [Mark Ransom on Stack Overflow](https://stackoverflow.com/a/3943023)
 * **Colourblindness Filters:** [Matthew Wickline and the Human-Computer Interaction Resource Network](http://web.archive.org/web/20090318054431/http://www.nofunc.com/Color_Blindness_Library) (web archive)
 
-## Citing Distinctipy
+## Citing distinctipy
 
 If you would like to cite distinctipy, please refer to the upload of the package on Zenodo: https://doi.org/10.5281/zenodo.3985191

distinctipy/__init__.py

@@ -12,7 +12,7 @@
 
 name = "distinctipy"
 
-__version__ = "1.2.1"
+__version__ = "1.2.2"
 
 # Expose these module names and their internals in the top-level API
 __external__ = ["distinctipy"]

docs/about.rst

@@ -1,12 +1,38 @@
-###########
+##############
 About
-###########
-distinctipy is a lightweight python package providing functions to generate
-colours that are visually distinct from one another.
-
-Commonly available qualitative colormaps provided by the likes of matplotlib
-generally have no more than 20 colours, but for some applications it is useful
-to have many more colours that are clearly different from one another.
-distinctipy can generate lists of colours of any length, with each new colour
-added to the list being as visually distinct from the pre-existing colours in
-the list as possible.
+##############
+
+Commonly available qualitative colormaps have no more than 20 colours,
+but for some applications it is useful to have many more colours that
+are clearly different from one another. distinctipy can generate lists
+of colours of any length, with each new colour added to the list being
+as visually distinct from the pre-existing colours in the list as
+possible. It can also be customised to take into account different
+types of colourblindness, as well as providing utility functions such
+as to select an appropriate font colour for any background colour.
+
+==================
+GitHub
+==================
+
+Check out our repo on `GitHub
+<https://github.com/alan-turing-institute/distinctipy>`_. We welcome
+questions and contributions of any kind.
+
+==================
+References
+==================
+
+*distinctipy* was heavily influenced and inspired by several web sources and
+stack overflow answers. In particular:
+
+* **Random generation of distinct colours:** `Andrew Dewes on GitHub <https://gist.github.com/adewes/5884820>`_
+* **Colour distance metric:** `Thiadmer Riemersma at CompuPhase <https://www.compuphase.com/cmetric.htm>`_
+* **Best text colour for background:** `Mark Ransom on Stack Overflow <https://stackoverflow.com/a/3943023>`_
+* **Colourblindness Filters:** `Matthew Wickline and the Human-Computer Interaction Resource Network <http://web.archive.org/web/20090318054431/http://www.nofunc.com/Color_Blindness_Library>`_ (web archive)
+
+=======================
+Citing distinctipy
+=======================
+
+If you would like to cite distinctipy, please refer to the upload of the package on `Zenodo <https://doi.org/10.5281/zenodo.3985191>`_.

docs/docs.rst → docs/api.rst

@@ -1,5 +1,5 @@
 ##############
-Documentation
+API Reference
 ##############
 
 distinctipy core

docs/conf.py

@@ -53,6 +53,11 @@
 #
 # html_theme = 'alabaster'
 html_theme = "sphinx_rtd_theme"
+html_logo = "../distinctipy_logo.png"
+html_theme_options = {
+    "logo_only": True,
+    "display_version": True,
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/index.rst

@@ -3,24 +3,17 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to distinctipy's documentation!
-=======================================
+distinctipy
+=================
 
-This page is a work in progress, for more details about distinctipy have a look at the repo on `GitHub
-<https://github.com/alan-turing-institute/distinctipy>`_.
+distinctipy is a lightweight python package providing functions to generate
+colours that are visually distinct from one another.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
-
+   
    about
-   docs
+   install
    usage.ipynb
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   api

docs/install.rst

@@ -0,0 +1,28 @@
+#################
+Installation
+#################
+
+*distinctipy* is tetsted on Python 3.7 - 3.10 (on Linux, Windows and Mac) and can be installed from PyPI using pip::
+
+    pip install distinctipy
+
+Alternatively, to install it from source::
+
+    git clone https://github.com/alan-turing-institute/distinctipy.git
+    cd distinctipy
+    pip install .
+
+=======================
+Optional Dependencies
+=======================
+
+Starting in version 1.2.1 `distinctipy` no longer bundles `matplotlib` or `pandas` in the default installation,
+to keep its footprint as small as possible. If you wish to view colours (e.g. with`distinctipy.color_swatch`)
+or examples you will need `matplotlib` and `pandas` installed. To do this, either install `distinctipy` with the
+optional flag::
+    
+    pip install 'distinctipy[optional]'
+
+Or install them separately::
+
+    pip install matplotlib pandas