Merge pull request #198 from vocalpy/add-logo

Add logo

README.md

@@ -1,16 +1,21 @@
-# crowsetta
+<br>
+<div align="center"><img src="./doc/_static/crowsetta-primary-logo.png" width="400"></div>
+<hr>
+
+## a tool to work with any format for annotating vocalizations
+
 [![Build Status](https://github.com/NickleDave/crowsetta/actions/workflows/ci.yml/badge.svg)](https://github.com/NickleDave/crowsetta/actions)
 [![Documentation Status](https://readthedocs.org/projects/crowsetta/badge/?version=latest)](https://crowsetta.readthedocs.io/en/latest/?badge=latest)
 [![DOI](https://zenodo.org/badge/159904494.svg)](https://zenodo.org/badge/latestdoi/159904494)
 [![PyPI version](https://badge.fury.io/py/crowsetta.svg)](https://badge.fury.io/py/crowsetta)
 [![codecov](https://codecov.io/gh/NickleDave/crowsetta/branch/main/graph/badge.svg?token=TXtNTxXKmb)](https://codecov.io/gh/NickleDave/crowsetta)
 
-`crowsetta` is a tool to work with any format for annotating vocalizations: speech, birdsong, 
+`crowsetta` is a tool to work with any format for annotating vocalizations: speech, birdsong,
 mouse ultrasonic calls (insert your favorite animal vocalization here).
-**The goal of** `crowsetta` **is to make sure that your ability to work with a dataset 
-of vocalizations does not depend on your ability to work with any given format for 
-annotating that dataset.** What `crowsetta` gives you is **not** yet another format for 
-annotation (I promise!); instead you get some nice data types that make it easy to 
+**The goal of** `crowsetta` **is to make sure that your ability to work with a dataset
+of vocalizations does not depend on your ability to work with any given format for
+annotating that dataset.** What `crowsetta` gives you is **not** yet another format for
+annotation (I promise!); instead you get some nice data types that make it easy to
 work with any format: namely, `Sequence`s made up of `Segment`s.
 
 ```Python
@@ -24,23 +29,23 @@ work with any format: namely, `Sequence`s made up of `Segment`s.
     >>> list_of_segments = [a_segment] * 3
     >>> seq = Sequence(segments=list_of_segments)
     >>> print(seq)
-    Sequence(segments=[Segment(label='a', onset_s=None, offset_s=None, onset_ind=16000, 
-    offset_ind=32000, file='bird21.wav'), Segment(label='a', onset_s=None, offset_s=None, 
-    onset_ind=16000, offset_ind=32000, file='bird21.wav'), Segment(label='a', onset_s=None, 
+    Sequence(segments=[Segment(label='a', onset_s=None, offset_s=None, onset_ind=16000,
+    offset_ind=32000, file='bird21.wav'), Segment(label='a', onset_s=None, offset_s=None,
+    onset_ind=16000, offset_ind=32000, file='bird21.wav'), Segment(label='a', onset_s=None,
     offset_s=None, onset_ind=16000, offset_ind=32000, file='bird21.wav')])
 ```
 
-You can load annotation from your format of choice into `Sequence`s of `Segment`s 
-(most conveniently with the `Transcriber`, as explained below) and then use the 
+You can load annotation from your format of choice into `Sequence`s of `Segment`s
+(most conveniently with the `Transcriber`, as explained below) and then use the
 `Sequence`s however you need to in your program.
 
-For example, if you want to loop through the `Segment`s of each `Sequence`s to 
+For example, if you want to loop through the `Segment`s of each `Sequence`s to
 pull syllables out of a spectrogram, you can do something like this, very Pythonically:
 
 ```Python
    >>> syllables_from_sequences = []
    >>> for a_seq in seq:
-   ...     seq_dict = seq.to_dict()  # convert to dict with 
+   ...     seq_dict = seq.to_dict()  # convert to dict with
    ...     spect = some_spectrogram_making_function(seq['file'])
    ...     syllables = []
    ...     for seg in seq.segments:
@@ -50,7 +55,7 @@ pull syllables out of a spectrogram, you can do something like this, very Python
 ```
 
 As mentioned above, `crowsetta` provides you with a `Transcriber` that comes equipped
-with convenience functions to do the work of converting for you. 
+with convenience functions to do the work of converting for you.
 
 ```Python
     from crowsetta import Transcriber
@@ -74,9 +79,9 @@ You can even easily adapt the `Transcriber` to use your own in-house format, lik
 - load comma-separated values files back into Python and convert to other formats
 - easily use with your own annotation format
 
-You might find it useful in any situation where you want 
-to share audio files of song and some associated annotations, 
-but you don't want to require the user to install a large 
+You might find it useful in any situation where you want
+to share audio files of song and some associated annotations,
+but you don't want to require the user to install a large
 application in order to work with the annotation files.
 
 ## Getting Started
@@ -145,4 +150,4 @@ The project is licensed under the [BSD license](./LICENSE).
 
 ### Citation
 If you use `crowsetta`, please cite the DOI:
-[![DOI](https://zenodo.org/badge/159904494.svg)](https://zenodo.org/badge/latestdoi/159904494)
+[![DOI](https://zenodo.org/badge/159904494.svg)](https://zenodo.org/badge/latestdoi/159904494)

doc/conf.py

@@ -50,8 +50,9 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
     'sphinx.ext.ifconfig',
-    'sphinxext.opengraph',
     'sphinx.ext.viewcode',
+    'sphinx_design',
+    'sphinxext.opengraph',
     'sphinx_tabs.tabs',
 ]
 
@@ -82,6 +83,18 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
+myst_enable_extensions = [
+    # "dollarmath",
+    # "amsmath",
+    # "deflist",
+    # "html_admonition",
+    # "html_image",
+    "colon_fence",
+    # "smartquotes",
+    # "replacements",
+    # "linkify",
+    # "substitution",
+]
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -90,11 +103,15 @@
 #
 html_theme = 'sphinx_book_theme'
 
+html_logo = "_static/crowsetta-primary-logo.png"
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    "logo_only": 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,

doc/index.md

@@ -13,21 +13,42 @@ execution:
   timeout: 120
 ---
 
-# crowsetta
+::::{grid}
+:reverse:
+:gutter: 2 1 1 1
+:margin: 4 4 1 1
 
-crowsetta is a Python tool to work with any format for annotating 
-animal vocalizations and other bioacoustics data. 
-Many of these formats are for files created 
-by GUI-based apps that enable users to annotate audio and/or spectrograms. 
-Annotations include the times when sound events start and stop, 
+:::{grid-item}
+:columns: 8
+:class: sd-fs-3
+
+A Python tool to work with any format for annotating 
+animal vocalizations and bioacoustics data.
+:::
+
+:::{grid-item}
+:columns: 4
+
+```{image} ./_static/crowsetta-secondary-logo.png
+:width: 150px
+```
+:::
+
+::::
+
+crowsetta provides a Pythonic way to work with annotation formats 
+for animal vocalizations and bioacoustics data. 
+These formats are used, for example, by 
+applications that enable users to annotate audio and/or spectrograms. 
+Such annotations typically include the times when sound events start and stop, 
 and labels that assign each sound to some set of classes 
 chosen by the annotator.
 crowsetta has built-in support for many widely used {ref}`formats <formats-index>` 
 such as {ref}`Audacity label tracks <aud-txt>`, 
 {ref}`Praat .TextGrid files <textgrid>`, 
 and {ref}`Raven .txt files <raven>`.
 
-```{figure} _static/example-textgrid-for-index.png
+:::{figure} _static/example-textgrid-for-index.png
 ---
 width: 90%
 figclass: margin-caption
@@ -42,9 +63,9 @@ Example song from
 [Bengalese finch song dataset](https://osf.io/r6paq/), 
 Tachibana and Morita 2021, adapated under 
 CC-By-4.0 License.**
-```
+:::
 
-```{figure} _static/example-raven-for-index.png
+:::{figure} _static/example-raven-for-index.png
 ---
 width: 90%
 figclass: margin-caption
@@ -60,7 +81,7 @@ Example song from
 ["An annotated set of audio recordings of Eastern North American birds containing frequency, time, and species information"](https://esajournals.onlinelibrary.wiley.com/doi/full/10.1002/ecy.3329), 
 Chronister et al., 2021, adapated under 
 CC0 1.0 License.**
-```
+:::
 
 Who would want to use crowsetta?
 Anyone that works with animal vocalizations 

pyproject.toml

@@ -41,17 +41,18 @@ test = [
     "pytest-cov >=2.12.0"
 ]
 doc = [
+    "jupyterlab >=3.0.3",
     "jupytext >=1.13.8",
     "librosa >=0.9.1",
     "myst-nb >=0.15.0",
     "pyprojroot >=0.2.0",
     "seaborn >=0.11.2",
     "Sphinx >=3.4.3",
-    "jupyterlab >=3.0.3",
-    "sphinxext-opengraph  >=0.5.1",
-    "sphinx-copybutton >=0.4.0",
     "sphinx-autobuild >= 2021.3.14",
     "sphinx-book-theme >=0.3.2",
+    "sphinx-copybutton >=0.4.0",
+    "sphinx-design >=0.2.0",
+    "sphinxext-opengraph  >=0.5.1",
     "sphinx-tabs >= 3.3.1",
 ]
 dev = [