From 45a9bf478e30597b5c91ddc76e544b65948085df Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Tue, 16 Apr 2019 04:36:34 -0500 Subject: [PATCH 01/34] Initial commit --- docs/Makefile | 19 +++++++ docs/make.bat | 35 ++++++++++++ docs/source/about/faqs.rst | 17 ++++++ docs/source/conf.py | 77 ++++++++++++++++++++++++++ docs/source/halo.rst | 30 +++++++++++ docs/source/index.rst | 107 +++++++++++++++++++++++++++++++++++++ docs/source/modules.rst | 7 +++ requirements-docs.txt | 4 ++ 8 files changed, 296 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/about/faqs.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/halo.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/modules.rst create mode 100644 requirements-docs.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..69fe55e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..4d9eb83 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/source/about/faqs.rst b/docs/source/about/faqs.rst new file mode 100644 index 0000000..6d6034f --- /dev/null +++ b/docs/source/about/faqs.rst @@ -0,0 +1,17 @@ +FAQs +==== + +Anticipated :abbr:`FAQs (Frequently Asked Questions)`. + +What spinners are compatible with Windows Operating System? +----------------------------------------------------------- + +Compatible spinners are defined in :meth:`~halo.halo.Halo._get_spinner()` from :mod:`halo.halo`: + +.. literalinclude:: ../../../halo/halo.py + :linenos: + :lineno-start: 251 + :language: python + :lines: 251-274 + +Currently, it defaults to ``line``. diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..7fd29ff --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,77 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +import recommonmark +from recommonmark.transform import AutoStructify + +sys.path.insert(0, os.path.abspath('../..')) + +# -- Project information ----------------------------------------------------- + +project = 'halo' +copyright = '2019, Manraj Singh' +author = 'Manraj Singh' + +# The full version, including alpha/beta/rc tags +release = '0.0.23' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', + 'recommonmark', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# Handle mapping of external module documentation written with Sphinx +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), +} + +autodoc_default_flags = ['members', 'undoc-members', 'private-members', + 'special-members', 'inherited-members', 'show-inheritance'] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# 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, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# -- Extension configuration ------------------------------------------------- + +def setup(app): + app.add_config_value('recommonmark_config', { + 'auto_toc_tree_section': 'Contents', + 'enable_eval_rst': True, + }, True) + app.add_transform(AutoStructify) diff --git a/docs/source/halo.rst b/docs/source/halo.rst new file mode 100644 index 0000000..e0a056a --- /dev/null +++ b/docs/source/halo.rst @@ -0,0 +1,30 @@ +halo package +============ + +Submodules +---------- + +halo.halo module +---------------- + +.. automodule:: halo.halo + :members: + :undoc-members: + :show-inheritance: + +halo.halo\_notebook module +-------------------------- + +.. automodule:: halo.halo_notebook + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: halo + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..7b8a845 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,107 @@ +.. halo documentation master file, created by + sphinx-quickstart on Mon Apr 15 04:18:11 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. image:: ../../art/halo.png + :height: 50px + :align: center + +halo +==== + +Beautiful spinners for terminal, IPython and Jupyter + +.. image:: ../../art/doge_spin.svg + +Install +------- + +.. code-block:: bash + + pip install halo + + +Usage +----- + +.. code-block:: python + + from halo import Halo + + spinner = Halo(text='Loading', spinner='dots') + spinner.start() + + # Run time consuming work here + # You can also change properties for spinner as and when you want + + spinner.stop() + +Alternatively, you can use halo with Python's ``with`` statement: + +.. code-block:: python + + from halo import Halo + + with Halo(text='Loading', spinner='dots'): + # Run time consuming work here + + +Finally, you can use halo as a decorator: + +.. code-block:: python + + from halo import Halo + + @Halo(text='Loading', spinner='dots') + def long_running_function(): + # Run time consuming work here + pass + + long_running_function() + +How to contribute? +------------------ + +Please see `Contributing guidelines`_ for more information. + +.. _Contributing guidelines: https://github.com/manrajgrover/halo/blob/master/.github/CONTRIBUTING.md + +Like it? +-------- + +🌟 this repo to show support. Let me know you liked it on `Twitter`_. +Also, share the `project`_. + +.. _Twitter: https://twitter.com/manrajsgrover +.. _project: https://twitter.com/intent/tweet?url=https%3A%2F%2Fgithub.com%2Fmanrajgrover%2Fhalo&via=manrajsgrover&text=Checkout%20%23halo%20-%20a%20beautiful%20%23terminal%20%23spinners%20library%20for%20%23python&hashtags=github%2C%20pypi + +Related +------- + +* `py-spinners`_ - Spinners in Python +* `py-log-symbols`_ - Log Symbols in Python +* `ora`_ - Elegant terminal spinners in JavaScript (inspiration behind this project) + +.. _py-spinners: https://github.com/manrajgrover/py-spinners +.. _py-log-symbols: https://github.com/manrajgrover/py-log-symbols +.. _ora: https://github.com/sindresorhus/ora + +License +------- + +`MIT`_ © Manraj Singh + +.. _MIT: https://github.com/manrajgrover/halo/blob/master/LICENSE + +.. toctree:: + :maxdepth: 2 + :caption: API Reference + + modules + +.. toctree:: + :maxdepth: 2 + :caption: About + + about/faqs diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..2611912 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +halo +==== + +.. toctree:: + :maxdepth: 4 + + halo diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 0000000..c220e4a --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,4 @@ +sphinx==2.0.1 +Jinja2==2.10.1 +sphinx-rtd-theme==0.4.3 +recommonmark==0.5.0 From 271cc1214183c0a2b854b2fc8c84715d1abbe57b Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Sat, 20 Apr 2019 00:26:24 -0500 Subject: [PATCH 02/34] Change depreciated autodoc_default_flags to autodoc_default_options --- docs/source/conf.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 7fd29ff..165c6c4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -52,8 +52,10 @@ 'python': ('https://docs.python.org/3/', None), } -autodoc_default_flags = ['members', 'undoc-members', 'private-members', - 'special-members', 'inherited-members', 'show-inheritance'] +autodoc_default_options = { + 'members': True, + 'private-members': True, +} # -- Options for HTML output ------------------------------------------------- From 56ff6d92d408b7541493230a02afbed298ac5370 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Sat, 20 Apr 2019 00:27:16 -0500 Subject: [PATCH 03/34] Add napoleon extension --- docs/source/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 165c6c4..6cb52b8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -36,6 +36,7 @@ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', + 'sphinx.ext.napoleon', 'recommonmark', ] From b1cccb221815930a8b66f439b619e0ef2e17ef9c Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Sat, 20 Apr 2019 01:17:00 -0500 Subject: [PATCH 04/34] Fix docstring spacing --- halo/halo.py | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/halo/halo.py b/halo/halo.py index 640d1af..3d47bb9 100644 --- a/halo/halo.py +++ b/halo/halo.py @@ -21,6 +21,7 @@ class Halo(object): """Halo library. + Attributes ---------- CLEAR_LINE : str @@ -33,6 +34,7 @@ class Halo(object): def __init__(self, text='', color='cyan', text_color=None, spinner=None, animation=None, placement='left', interval=-1, enabled=True, stream=sys.stdout): """Constructs the Halo object. + Parameters ---------- text : str, optional @@ -91,6 +93,7 @@ def clean_up(): def __enter__(self): """Starts the spinner on a separate thread. For use in context managers. + Returns ------- self @@ -114,6 +117,7 @@ def wrapped(*args, **kwargs): @property def spinner(self): """Getter for spinner property. + Returns ------- dict @@ -124,6 +128,7 @@ def spinner(self): @spinner.setter def spinner(self, spinner=None): """Setter for spinner property. + Parameters ---------- spinner : dict, str @@ -137,6 +142,7 @@ def spinner(self, spinner=None): @property def text(self): """Getter for text property. + Returns ------- str @@ -147,6 +153,7 @@ def text(self): @text.setter def text(self, text): """Setter for text property. + Parameters ---------- text : str @@ -157,6 +164,7 @@ def text(self, text): @property def text_color(self): """Getter for text color property. + Returns ------- str @@ -167,6 +175,7 @@ def text_color(self): @text_color.setter def text_color(self, text_color): """Setter for text color property. + Parameters ---------- text_color : str @@ -177,6 +186,7 @@ def text_color(self, text_color): @property def color(self): """Getter for color property. + Returns ------- str @@ -187,6 +197,7 @@ def color(self): @color.setter def color(self, color): """Setter for color property. + Parameters ---------- color : str @@ -197,6 +208,7 @@ def color(self, color): @property def placement(self): """Getter for placement property. + Returns ------- str @@ -207,6 +219,7 @@ def placement(self): @placement.setter def placement(self, placement): """Setter for placement property. + Parameters ---------- placement: str @@ -220,6 +233,7 @@ def placement(self, placement): @property def spinner_id(self): """Getter for spinner id + Returns ------- str @@ -230,6 +244,7 @@ def spinner_id(self): @property def animation(self): """Getter for animation property. + Returns ------- str @@ -240,6 +255,7 @@ def animation(self): @animation.setter def animation(self, animation): """Setter for animation property. + Parameters ---------- animation: str @@ -251,10 +267,12 @@ def animation(self, animation): def _get_spinner(self, spinner): """Extracts spinner value from options and returns value containing spinner frames and interval, defaults to 'dots' spinner. + Parameters ---------- spinner : dict, str Contains spinner value or type of spinner to be used + Returns ------- dict @@ -275,6 +293,7 @@ def _get_spinner(self, spinner): def _get_text(self, text): """Creates frames based on the selected animation + Returns ------- self @@ -321,6 +340,7 @@ def _get_text(self, text): def clear(self): """Clears the line and returns cursor to the start. of line + Returns ------- self @@ -346,6 +366,7 @@ def _render_frame(self): def render(self): """Runs the render until thread flag is set. + Returns ------- self @@ -358,6 +379,7 @@ def render(self): def frame(self): """Builds and returns the frame to be rendered + Returns ------- self @@ -380,6 +402,7 @@ def frame(self): def text_frame(self): """Builds and returns the text frame to be rendered + Returns ------- self @@ -404,10 +427,12 @@ def text_frame(self): def start(self, text=None): """Starts the spinner on a separate thread. + Parameters ---------- text : None, optional Text to be used alongside spinner + Returns ------- self @@ -432,6 +457,7 @@ def start(self, text=None): def stop(self): """Stops the spinner and clears the line. + Returns ------- self @@ -454,10 +480,12 @@ def stop(self): def succeed(self, text=None): """Shows and persists success symbol and text and exits. + Parameters ---------- text : None, optional Text to be shown alongside success symbol. + Returns ------- self @@ -466,10 +494,12 @@ def succeed(self, text=None): def fail(self, text=None): """Shows and persists fail symbol and text and exits. + Parameters ---------- text : None, optional Text to be shown alongside fail symbol. + Returns ------- self @@ -478,10 +508,12 @@ def fail(self, text=None): def warn(self, text=None): """Shows and persists warn symbol and text and exits. + Parameters ---------- text : None, optional Text to be shown alongside warn symbol. + Returns ------- self @@ -490,10 +522,12 @@ def warn(self, text=None): def info(self, text=None): """Shows and persists info symbol and text and exits. + Parameters ---------- text : None, optional Text to be shown alongside info symbol. + Returns ------- self @@ -502,6 +536,7 @@ def info(self, text=None): def stop_and_persist(self, symbol=' ', text=None): """Stops the spinner and persists the final frame to be shown. + Parameters ---------- symbol : str, optional From 64b749fe150d75efcbbe2aac0290ca35125a55f6 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Sat, 20 Apr 2019 01:17:17 -0500 Subject: [PATCH 05/34] Fix docstring spacing --- halo/halo_notebook.py | 1 + 1 file changed, 1 insertion(+) diff --git a/halo/halo_notebook.py b/halo/halo_notebook.py index 80b83fa..3827210 100644 --- a/halo/halo_notebook.py +++ b/halo/halo_notebook.py @@ -72,6 +72,7 @@ def start(self, text=None): def stop_and_persist(self, symbol=' ', text=None): """Stops the spinner and persists the final frame to be shown. + Parameters ---------- symbol : str, optional From 9a90063cabdb28bafe2f9c8250fca6e4b5425c96 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Sat, 20 Apr 2019 01:22:06 -0500 Subject: [PATCH 06/34] Fix line numbers in halo.py include --- docs/source/about/faqs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/about/faqs.rst b/docs/source/about/faqs.rst index 6d6034f..1ab38b7 100644 --- a/docs/source/about/faqs.rst +++ b/docs/source/about/faqs.rst @@ -10,8 +10,8 @@ Compatible spinners are defined in :meth:`~halo.halo.Halo._get_spinner()` from : .. literalinclude:: ../../../halo/halo.py :linenos: - :lineno-start: 251 + :lineno-start: 267 :language: python - :lines: 251-274 + :lines: 267-292 Currently, it defaults to ``line``. From e65f0f995a716ec8c9b7e03e54a4c35f82f6dbe9 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Sat, 20 Apr 2019 02:23:13 -0500 Subject: [PATCH 07/34] Add symlink to .github/CONTRIBUTING.md --- docs/source/about/CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) create mode 120000 docs/source/about/CONTRIBUTING.md diff --git a/docs/source/about/CONTRIBUTING.md b/docs/source/about/CONTRIBUTING.md new file mode 120000 index 0000000..724d177 --- /dev/null +++ b/docs/source/about/CONTRIBUTING.md @@ -0,0 +1 @@ +../../../.github/CONTRIBUTING.md \ No newline at end of file From 74c85a5c208c22c280b5f9407254308e80781834 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Sat, 20 Apr 2019 02:23:44 -0500 Subject: [PATCH 08/34] Add symlink to DEVELOPMENT.md --- docs/source/about/DEVELOPMENT.md | 1 + 1 file changed, 1 insertion(+) create mode 120000 docs/source/about/DEVELOPMENT.md diff --git a/docs/source/about/DEVELOPMENT.md b/docs/source/about/DEVELOPMENT.md new file mode 120000 index 0000000..818df22 --- /dev/null +++ b/docs/source/about/DEVELOPMENT.md @@ -0,0 +1 @@ +../../../DEVELOPMENT.md \ No newline at end of file From 26fed6318a185d65bcaaea25952f13ef55510092 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Sat, 20 Apr 2019 02:24:56 -0500 Subject: [PATCH 09/34] Add DEVELOPMENT.md and CONTRIBUTING.md to toctree --- docs/source/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index 7b8a845..096563e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -105,3 +105,5 @@ License :caption: About about/faqs + about/DEVELOPMENT + Contributing From 6a2693a93a09dde616b7039858f8e517698cf148 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Sat, 20 Apr 2019 02:47:38 -0500 Subject: [PATCH 10/34] Remove How to contribute? section --- docs/source/index.rst | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 096563e..1b72855 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -60,13 +60,6 @@ Finally, you can use halo as a decorator: long_running_function() -How to contribute? ------------------- - -Please see `Contributing guidelines`_ for more information. - -.. _Contributing guidelines: https://github.com/manrajgrover/halo/blob/master/.github/CONTRIBUTING.md - Like it? -------- From a9bb9c1df9656a4822a2a979e126602e5d1b73cd Mon Sep 17 00:00:00 2001 From: Jose A Lerma III Date: Sat, 20 Apr 2019 14:07:27 -0500 Subject: [PATCH 11/34] Fix typo in docstring --- halo/halo.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/halo/halo.py b/halo/halo.py index 3d47bb9..192228f 100644 --- a/halo/halo.py +++ b/halo/halo.py @@ -338,8 +338,7 @@ def _get_text(self, text): } def clear(self): - """Clears the line and returns cursor to the start. - of line + """Clears the line and returns cursor to the start of line. Returns ------- From ad367abb44aafa0231dcee63b385b5cff4af6118 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 22 Apr 2019 05:22:12 -0500 Subject: [PATCH 12/34] Add comment to autodoc_default_options and add autoclass_content --- docs/source/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 6cb52b8..cb0ce0e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -53,11 +53,15 @@ 'python': ('https://docs.python.org/3/', None), } +# Document private members autodoc_default_options = { 'members': True, 'private-members': True, } +# Document class' and __init__ docstrings combined +autoclass_content = 'both' + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for From 69d58060844338bda5e3095cc0f8bc694e34a73f Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 22 Apr 2019 05:23:11 -0500 Subject: [PATCH 13/34] Updated docstrings to match README.md API section --- halo/halo.py | 57 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 37 insertions(+), 20 deletions(-) diff --git a/halo/halo.py b/halo/halo.py index 192228f..da0b495 100644 --- a/halo/halo.py +++ b/halo/halo.py @@ -38,26 +38,36 @@ def __init__(self, text='', color='cyan', text_color=None, spinner=None, Parameters ---------- text : str, optional - Text to display. + Text shown along with spinner. text_color : str, optional - Color of the text. + Color of the text to dislpay. Can be ``grey``, ``red``, ``green``, + ``yellow``, ``blue``, ``magenta``, ``cyan``, or ``white``. Defaults to ``None``. color : str, optional - Color of the text to display. + Color of the spinner. Can be ``grey``, ``red``, ``green``, + ``yellow``, ``blue``, ``magenta``, ``cyan``, or ``white``. Defaults to ``cyan``. spinner : str|dict, optional String or dictionary representing spinner. String can be one of 60+ spinners - supported. + supported. If a dict is passed, it should define ``interval`` and ``frames``. + Something like:: + + { + 'interval': 100, + 'frames': ['-', '+', '*', '+', '-'] + } + animation: str, optional - Animation to apply if text is too large. Can be one of `bounce`, `marquee`. - Defaults to ellipses. + Animation to apply if text is too large. Can be ``bounce`` or ``marquee``. + If no animation is defined, the text will be ellipsed. placement: str, optional - Side of the text to place the spinner on. Can be `left` or `right`. - Defaults to `left`. - interval : integer, optional + Side of the text to place the spinner on. Can be ``left`` or ``right``. + Defaults to ``left``. + interval : int, optional Interval between each frame of the spinner in milliseconds. - enabled : boolean, optional - Spinner enabled or not. + Defaults to spinner interval (recommended). + enabled : bool, optional + Enable or disable the spinner. Defaults to ``True``. stream : io, optional - Output. + Stream to write the output. Defaults to ``sys.stdout``. """ self._color = color self._animation = animation @@ -266,7 +276,7 @@ def animation(self, animation): def _get_spinner(self, spinner): """Extracts spinner value from options and returns value - containing spinner frames and interval, defaults to 'dots' spinner. + containing spinner frames and interval, defaults to ``dots`` spinner. Parameters ---------- @@ -478,7 +488,8 @@ def stop(self): return self def succeed(self, text=None): - """Shows and persists success symbol and text and exits. + """Stops the spinner and changes symbol to ``✔``. If text is provided, + it is persisted else current text is persisted. Parameters ---------- @@ -492,7 +503,8 @@ def succeed(self, text=None): return self.stop_and_persist(symbol=LogSymbols.SUCCESS.value, text=text) def fail(self, text=None): - """Shows and persists fail symbol and text and exits. + """Stops the spinner and changes symbol to ``✖``. If text is provided, + it is persisted else current text is persisted. Parameters ---------- @@ -506,7 +518,8 @@ def fail(self, text=None): return self.stop_and_persist(symbol=LogSymbols.ERROR.value, text=text) def warn(self, text=None): - """Shows and persists warn symbol and text and exits. + """Stops the spinner and changes symbol to ``⚠``. If text is provided, + it is persisted else current text is persisted. Parameters ---------- @@ -520,7 +533,8 @@ def warn(self, text=None): return self.stop_and_persist(symbol=LogSymbols.WARNING.value, text=text) def info(self, text=None): - """Shows and persists info symbol and text and exits. + """Stops the spinner and changes symbol to `ℹ`. If text is provided, + it is persisted else current text is persisted. Parameters ---------- @@ -534,14 +548,17 @@ def info(self, text=None): return self.stop_and_persist(symbol=LogSymbols.INFO.value, text=text) def stop_and_persist(self, symbol=' ', text=None): - """Stops the spinner and persists the final frame to be shown. + """Stops the spinner and changes symbol and text. Parameters ---------- symbol : str, optional - Symbol to be shown in final frame + Symbol to replace the spinner with. Defaults to ``' '``. text: str, optional - Text to be shown in final frame + Text to be persisted. Defaults to instance text. + + + .. image:: https://raw.github.com/manrajgrover/halo/master/art/persist_spin.svg?sanitize=true Returns ------- From a6852f602afb19873bc259c184ba8d70b29e3155 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 22 Apr 2019 06:34:03 -0500 Subject: [PATCH 14/34] Fix line numbers in halo.py include --- docs/source/about/faqs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/about/faqs.rst b/docs/source/about/faqs.rst index 1ab38b7..70114aa 100644 --- a/docs/source/about/faqs.rst +++ b/docs/source/about/faqs.rst @@ -10,8 +10,8 @@ Compatible spinners are defined in :meth:`~halo.halo.Halo._get_spinner()` from : .. literalinclude:: ../../../halo/halo.py :linenos: - :lineno-start: 267 + :lineno-start: 277 :language: python - :lines: 267-292 + :lines: 277-302 Currently, it defaults to ``line``. From ce4ef6382d37b182eb1d55f17aa230a0a4174f79 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 16:11:19 -0500 Subject: [PATCH 15/34] Add badges --- docs/source/index.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index 1b72855..697d062 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,6 +10,21 @@ halo ==== +.. image:: https://travis-ci.org/manrajgrover/halo.svg?branch=master + :target: https://travis-ci.org/manrajgrover/halo + :alt: Travis CI Build Status +.. image:: https://ci.appveyor.com/api/projects/status/wa6t414gltr403ff?svg=true + :target: https://ci.appveyor.com/project/manrajgrover/halo + :alt: AppVeyor Build status +.. image:: https://coveralls.io/repos/github/manrajgrover/halo/badge.svg?branch=master + :target: https://coveralls.io/github/manrajgrover/halo?branch=master + :alt: Coveralls Status +.. image:: https://img.shields.io/pypi/v/halo.svg + :target: https://github.com/manrajgrover/halo + :alt: PyPI +.. image:: https://img.shields.io/badge/awesome-yes-green.svg + :alt: awesome + Beautiful spinners for terminal, IPython and Jupyter .. image:: ../../art/doge_spin.svg From a8c9dc98332fe9356b3f1204f305709d6a295056 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 16:25:50 -0500 Subject: [PATCH 16/34] Add sphinx linkcheck --- tox.ini | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 1fd25df..563fab6 100644 --- a/tox.ini +++ b/tox.ini @@ -5,7 +5,8 @@ envlist = py35, py36, py37, - lint + lint, + sphinx skip_missing_interpreters = True @@ -25,3 +26,8 @@ commands = [testenv:lint] commands = pylint --errors-only --rcfile={toxinidir}/.pylintrc --output-format=colorized halo + +[testenv:sphinx] +deps = + -r{toxinidir}/requirements-docs.txt +commands = sphinx-build -M linkcheck {toxinidir}/docs/source {toxinidir}/docs/build From 65972d6c71a5aa0b4113d5764241feedb33a7e10 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 16:31:31 -0500 Subject: [PATCH 17/34] Fix broken link --- .github/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f124a0e..86b979b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,7 +2,7 @@ ## Development Guidelines -Please read [development guidelines](https://github.com/manrajgrover/halo/blob/master/DEVELOPMENT.md) inorder to setup dev environment and run tests. +Please read [development guidelines](./DEVELOPMENT.md) inorder to setup dev environment and run tests. ## Steps to contribute From 6dded1604220ca9a22206769d6860879537ab0e1 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 17:02:11 -0500 Subject: [PATCH 18/34] [Builds] Add sphinx toxenv to appveyor --- appveyor.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/appveyor.yml b/appveyor.yml index 9049106..f0fecb1 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -45,6 +45,12 @@ environment: PYTHON_VERSION: '2.7' PYTHON_ARCH: '32' + - TOXENV: 'sphinx' + TOXPYTHON: C:\Python37\python.exe + PYTHON_HOME: C:\Python37 + PYTHON_VERSION: '3.7' + PYTHON_ARCH: '32' + matrix: fast_finish: true From 065977bf7208b2e75ef6a96031600fceacd7015b Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 17:08:09 -0500 Subject: [PATCH 19/34] [Builds] Add sphinx toxenv to travis --- .travis.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.travis.yml b/.travis.yml index 58a78f6..b8af90c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -18,6 +18,10 @@ matrix: dist: xenial sudo: true env: TOXENV=py37 + - python: '3.7' + dist: xenial + sudo: true + env: TOXENV=sphinx fast_finish: true install: - pip install tox coveralls From 269052e391ccbc85482ebf1c858794a8b2a25fdf Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 17:58:47 -0500 Subject: [PATCH 20/34] Move DEVELOPMENT.md to .github --- DEVELOPMENT.md => .github/DEVELOPMENT.md | 0 docs/source/about/DEVELOPMENT.md | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename DEVELOPMENT.md => .github/DEVELOPMENT.md (100%) diff --git a/DEVELOPMENT.md b/.github/DEVELOPMENT.md similarity index 100% rename from DEVELOPMENT.md rename to .github/DEVELOPMENT.md diff --git a/docs/source/about/DEVELOPMENT.md b/docs/source/about/DEVELOPMENT.md index 818df22..3db222e 120000 --- a/docs/source/about/DEVELOPMENT.md +++ b/docs/source/about/DEVELOPMENT.md @@ -1 +1 @@ -../../../DEVELOPMENT.md \ No newline at end of file +../../../.github/DEVELOPMENT.md \ No newline at end of file From a4fea93236145ed2af73daa25810a1f5ecb5d2dd Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 18:23:22 -0500 Subject: [PATCH 21/34] Downgrade sphinx from 2.0.1 to 1.8.5 for python2.7 --- requirements-docs.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements-docs.txt b/requirements-docs.txt index c220e4a..23dd795 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,4 +1,4 @@ -sphinx==2.0.1 +sphinx==1.8.5 Jinja2==2.10.1 sphinx-rtd-theme==0.4.3 recommonmark==0.5.0 From 70b8f7df047357134c81351bfbe98ecfd504d390 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 18:23:46 -0500 Subject: [PATCH 22/34] Change autodoc_default_options to autodoc_default_flags --- docs/source/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index cb0ce0e..c3376fe 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -54,10 +54,10 @@ } # Document private members -autodoc_default_options = { - 'members': True, - 'private-members': True, -} +autodoc_default_flags = [ + 'members', + 'private-members' +] # Document class' and __init__ docstrings combined autoclass_content = 'both' From 4fa53b597562af25e906acad43f281633321705b Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 18:24:49 -0500 Subject: [PATCH 23/34] Add master_doc --- docs/source/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index c3376fe..2b14b40 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -59,6 +59,9 @@ 'private-members' ] +# Define master document +master_doc = 'index' + # Document class' and __init__ docstrings combined autoclass_content = 'both' From 747c931c09d94a6b13b55dadd3de74144a9dfaf5 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 18:39:53 -0500 Subject: [PATCH 24/34] Add DummyBuilder to sphinx testenv commands --- tox.ini | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 6f6f111..5e25fb9 100644 --- a/tox.ini +++ b/tox.ini @@ -32,4 +32,6 @@ commands = [testenv:sphinx] deps = -r{toxinidir}/requirements-docs.txt -commands = sphinx-build -M linkcheck {toxinidir}/docs/source {toxinidir}/docs/build +commands = + sphinx-build -M dummy {toxinidir}/docs/source {toxinidir}/docs/build + sphinx-build -M linkcheck {toxinidir}/docs/source {toxinidir}/docs/build From 2f43f043520ffa4d187149929de0a5839020aa49 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 19:05:11 -0500 Subject: [PATCH 25/34] Add Building Documentation section --- .github/DEVELOPMENT.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/.github/DEVELOPMENT.md b/.github/DEVELOPMENT.md index e2fe4d5..dc80e8d 100644 --- a/.github/DEVELOPMENT.md +++ b/.github/DEVELOPMENT.md @@ -42,3 +42,43 @@ For checking lint issues: ```bash $ tox -e lint ``` + +### Building Documentation + +To install documentation dependencies, run: + +```bash +$ pip install -r requirements-docs.txt +``` + +To build the docs, change directories and then run the `html` make target: + +```bash +$ cd docs +$ make html +``` + +Documentation will be located in `docs/build/html`. + +#### Adding Documentation + +After editing or adding to the module's docstrings, update the Sphinx documentation with `sphinx-apidoc`, +then rebuild the html pages: + +```bash +$ sphinx-apidoc -f -o ./docs/source halo +$ cd docs +$ make html +``` + +#### Testing Documentation + +Documentation testing is integrated with `tox`. + +Simply run: + +```bash +$ tox -e sphinx +``` + +If `linkcheck` fails, a list of broken external links will be located in `docs/build/linkcheck/output.txt`. From bb8241124df7f2cd972162e59ebeb31075d9f90d Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 19:48:19 -0500 Subject: [PATCH 26/34] Add clearing output directory to Adding Documentation section --- .github/DEVELOPMENT.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/DEVELOPMENT.md b/.github/DEVELOPMENT.md index dc80e8d..b8fe290 100644 --- a/.github/DEVELOPMENT.md +++ b/.github/DEVELOPMENT.md @@ -63,11 +63,12 @@ Documentation will be located in `docs/build/html`. #### Adding Documentation After editing or adding to the module's docstrings, update the Sphinx documentation with `sphinx-apidoc`, -then rebuild the html pages: +clear the output directory, then rebuild the html pages: ```bash $ sphinx-apidoc -f -o ./docs/source halo $ cd docs +$ make clean $ make html ``` From 35a4123fe0d99e590e6c9598bd73d9e050eff1e6 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 19:57:30 -0500 Subject: [PATCH 27/34] Fix line numbers in halo.py include --- docs/source/about/faqs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/about/faqs.rst b/docs/source/about/faqs.rst index 70114aa..ef55707 100644 --- a/docs/source/about/faqs.rst +++ b/docs/source/about/faqs.rst @@ -10,8 +10,8 @@ Compatible spinners are defined in :meth:`~halo.halo.Halo._get_spinner()` from : .. literalinclude:: ../../../halo/halo.py :linenos: - :lineno-start: 277 + :lineno-start: 320 :language: python - :lines: 277-302 + :lines: 320-345 Currently, it defaults to ``line``. From 2167ae00f3a40bfa4982bfa28f3ca9617627ce45 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 19:58:04 -0500 Subject: [PATCH 28/34] Add adding to docs/source folder to Adding Documentation section --- .github/DEVELOPMENT.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/DEVELOPMENT.md b/.github/DEVELOPMENT.md index b8fe290..7c59730 100644 --- a/.github/DEVELOPMENT.md +++ b/.github/DEVELOPMENT.md @@ -72,6 +72,15 @@ $ make clean $ make html ``` +After adding content to the `docs/source` folder, update the Sphinx documentation by clearing the output directory, +then rebuilding the html pages: + +```bash +$ cd docs +$ make clean +$ make html +``` + #### Testing Documentation Documentation testing is integrated with `tox`. From d0b6d1aa5a02e2e7fd844a496727821d1a65cbc2 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 20:05:52 -0500 Subject: [PATCH 29/34] Add version --- docs/source/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 2b14b40..dfd4f76 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,6 +23,9 @@ copyright = '2019, Manraj Singh' author = 'Manraj Singh' +# The short X.Y version +version = '0.0' + # The full version, including alpha/beta/rc tags release = '0.0.23' From 272f1071490da1cb6f59e96a9a1fd86a850ff413 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 20:06:06 -0500 Subject: [PATCH 30/34] Bump release --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index dfd4f76..1450748 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -27,7 +27,7 @@ version = '0.0' # The full version, including alpha/beta/rc tags -release = '0.0.23' +release = '0.0.28' # -- General configuration --------------------------------------------------- From f76b256a9a60fa99e05836b8ff47f6eb1edd5149 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 20:34:46 -0500 Subject: [PATCH 31/34] Add version TODO --- docs/source/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 1450748..1fc5210 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,6 +23,7 @@ copyright = '2019, Manraj Singh' author = 'Manraj Singh' +# TODO: Single source version info # The short X.Y version version = '0.0' From 24db0a5dd9deef20bbeda29a3f14ad6894087b10 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 21:24:11 -0500 Subject: [PATCH 32/34] Fix _check_stream docstring spacing --- halo/halo.py | 1 + 1 file changed, 1 insertion(+) diff --git a/halo/halo.py b/halo/halo.py index dddd2f8..d53af66 100644 --- a/halo/halo.py +++ b/halo/halo.py @@ -276,6 +276,7 @@ def animation(self, animation): def _check_stream(self): """Returns whether the stream is open, and if applicable, writable + Returns ------- bool From 7770c8413e3ad218b43b7703f08336268fd03088 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 21:24:23 -0500 Subject: [PATCH 33/34] Fix _write docstring spacing --- halo/halo.py | 1 + 1 file changed, 1 insertion(+) diff --git a/halo/halo.py b/halo/halo.py index d53af66..96e6619 100644 --- a/halo/halo.py +++ b/halo/halo.py @@ -298,6 +298,7 @@ def _check_stream(self): def _write(self, s): """Write to the stream, if writable + Parameters ---------- s : str From ed2681e801784a4e829d9b37d9b457f227b604f3 Mon Sep 17 00:00:00 2001 From: JoseALermaIII Date: Mon, 23 Sep 2019 21:32:05 -0500 Subject: [PATCH 34/34] Fix line numbers in halo.py include --- docs/source/about/faqs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/about/faqs.rst b/docs/source/about/faqs.rst index ef55707..116f7b0 100644 --- a/docs/source/about/faqs.rst +++ b/docs/source/about/faqs.rst @@ -10,8 +10,8 @@ Compatible spinners are defined in :meth:`~halo.halo.Halo._get_spinner()` from : .. literalinclude:: ../../../halo/halo.py :linenos: - :lineno-start: 320 + :lineno-start: 322 :language: python - :lines: 320-345 + :lines: 322-347 Currently, it defaults to ``line``.