diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /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% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..d4be59d --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,87 @@ +@import url("css/theme.css"); + +.modname { + font-size: 0.8em; + opacity: 0.4; +} +.modname::before { + content: '- '; +} +.title { + font-weight: bold; + font-size: 1.2em; + background-color: #eee; + display: block; + padding: 1px 5px; + border-left: 2px solid #ddd; +} + +/*colour of the text in the toc*/ +.wy-menu-vertical header, .wy-menu-vertical p.caption{ + color: #b26d46;; +} + +/*colour of the top left header*/ +.wy-side-nav-search{ + background-color: #31465a; +} + +/*colours of the class definitions*/ +.rst-content dl:not(.docutils) dt{ + background: #e2d7d1; + color: #0b2852; + border-top: solid 3px #31465a; +} + +/*colour of the link in the class defintions*/ +.rst-content .viewcode-link, .rst-content .viewcode-back{ + color: #4b674a; +} + +/*colour of the function definitions*/ +.rst-content dl:not(.docutils) dl dt{ + border-left: solid 3px #31465a; + background: #e2d7d1; + color: #0b2852; +} + +/*colour of the link in the function definitions*/ +.rst-content .viewcode-link, .rst-content .viewcode-back{ + color: #4b674a; +} + +/*edit the width of the body*/ +.wy-nav-content{ + max-width: 1200px; +} + +/*code example blocks*/ +.rst-content pre.literal-block, .rst-content div[class^="highlight"] pre, .rst-content .linenodiv pre{ + background: #b4bec8; + color: black; + /*border-style: solid;*/ + /*border-width: thin;*/ +} + +/*colour of inline code blocks using ``*/ +.rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal{ + color: #b26d46; +} + +/* Change code blocks font and bump up font size slightly (normally 12px)*/ +.rst-content pre.literal-block, .rst-content div[class^="highlight"] pre, .rst-content .linenodiv pre { + font-family: 'Inconsolata', monospace !important; + font-size: 14px !important; + white-space: pre-wrap; +} + +/* Change code descriptions and literal blocks (inline code via ``) to match the normal font size being used in the sphinx_RTD_theme text (normally 14px)*/ +.rst-content dl:not(.docutils) tt.descname,.rst-content dl:not(.docutils) tt.descclassname,.rst-content dl:not(.docutils) tt.descname,.rst-content dl:not(.docutils) code.descname,.rst-content dl:not(.docutils) tt.descclassname,.rst-content dl:not(.docutils) code.descclassname, code.docutils { + font-family: 'Inconsolata', monospace !important; + font-size: 14px !important; +} + +/*variables text*/ +dl.class > dd > table.docutils.field-list tbody tr.field-odd.field th.field-name::before{ + content: '(Class Attributes) '; +} diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst new file mode 100644 index 0000000..f1bb7a6 --- /dev/null +++ b/docs/source/changelog.rst @@ -0,0 +1,20 @@ +Changelog +========== + +All notable changes to this project will be documented in this file. + +The format is based on `Keep a Changelog`_ + +.. _https://keepachangelog.com/en/1.0.0/ + +and this project adheres to `Semantic Versioning`_ + +.. _https://semver.org/spec/v2.0.0.html + +[1.0.0] - 2020-03-07 +------------------------ + +Added +###### + +- Initial version diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..c6a8fb5 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,97 @@ +# 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: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- 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 +# sys.path.insert(0, os.path.abspath('.')) +import musicbrainzapi +from musicbrainzapi.__version__ import __version__ +import sphinx_rtd_theme +import sphinx_click + +# -- Project information ----------------------------------------------------- + +project = 'musicbrainzapi' +copyright = '2020, Daniel Tomlinson' +author = 'Daniel Tomlinson' + +# The full version, including alpha/beta/rc tags +release = __version__ + + +# -- 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.napoleon', + 'sphinx.ext.todo', + 'sphinx_click.ext', +] + +# -- Napoleon Settings ----------------------------------------------------- +napoleon_google_docstring = False +napoleon_numpy_docstring = True +napoleon_include_init_with_doc = True +napoleon_include_private_with_doc = True +napoleon_include_special_with_doc = False +napoleon_use_admonition_for_examples = False +napoleon_use_admonition_for_notes = False +napoleon_use_admonition_for_references = False +napoleon_use_ivar = True +napoleon_use_param = True +napoleon_use_rtype = True +napoleon_use_keyword = True +autodoc_member_order = 'bysource' + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The master toctree document. +master_doc = 'index' + +# 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 = [] + + +# -- 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_theme = "sphinx_rtd_theme" +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +html_static_path = ['_static'] +html_context = {'css_files': ['_static/custom.css']} +html_theme_options = { + 'collapse_navigation': True, + 'display_version': True, + 'prev_next_buttons_location': 'both', + #'navigation_depth': 3, +} + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# Enable todo +todo_include_todos = True diff --git a/docs/source/global.rst b/docs/source/global.rst new file mode 100644 index 0000000..b117004 --- /dev/null +++ b/docs/source/global.rst @@ -0,0 +1,5 @@ +.. role:: modname + :class: modname + +.. role:: title + :class: title diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..176e544 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,3 @@ +Table of Contents +================= +.. include:: toc.rst diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst new file mode 100644 index 0000000..0934562 --- /dev/null +++ b/docs/source/introduction.rst @@ -0,0 +1,13 @@ +musicbrainzapi +=============== + +.. image:: https://img.shields.io/readthedocs/panaetius?style=for-the-badge :target: https://panaetius.readthedocs.io/en/latest/?badge=latest + :alt: Documentation Status + +.. image:: https://img.shields.io/github/v/tag/dtomlinson91/musicbrainzapi-cv-airelogic?style=for-the-badge :alt: GitHub tag (latest by date) + +.. image:: https://img.shields.io/github/commit-activity/m/dtomlinson91/musicbrainzapi-cv-airelogic?style=for-the-badge :alt: GitHub commit activity + +.. image:: https://img.shields.io/github/issues/dtomlinson91/musicbrainzapi-cv-airelogic?style=for-the-badge :alt: GitHub issues + +.. image:: https://img.shields.io/github/license/dtomlinson91/musicbrainzapi-cv-airelogic?style=for-the-badge :alt: GitHubtbc diff --git a/docs/source/modules/musicbrainzapi.api.authenticate.rst b/docs/source/modules/musicbrainzapi.api.authenticate.rst new file mode 100644 index 0000000..805ba56 --- /dev/null +++ b/docs/source/modules/musicbrainzapi.api.authenticate.rst @@ -0,0 +1,10 @@ + .. include:: ../global.rst + +musicbrainzapi.api.authenticate :modname:`musicbrainzapi.api.authenticate module` +------------------------------------------------------------------------------------------ + +.. automodule:: musicbrainzapi.api.authenticate + :members: + :undoc-members: + :show-inheritance: + :private-members: diff --git a/docs/source/modules/musicbrainzapi.api.lyrics.builder.rst b/docs/source/modules/musicbrainzapi.api.lyrics.builder.rst new file mode 100644 index 0000000..38d5e4b --- /dev/null +++ b/docs/source/modules/musicbrainzapi.api.lyrics.builder.rst @@ -0,0 +1,10 @@ + .. include:: ../global.rst + +musicbrainzapi.api.lyrics.builder :modname:`musicbrainzapi.api.lyrics.builder` +------------------------------------------------------------------------------- + +.. automodule:: musicbrainzapi.api.lyrics.builder + :members: + :undoc-members: + :show-inheritance: + :private-members: diff --git a/docs/source/modules/musicbrainzapi.api.lyrics.concrete_builder.rst b/docs/source/modules/musicbrainzapi.api.lyrics.concrete_builder.rst new file mode 100644 index 0000000..4acc336 --- /dev/null +++ b/docs/source/modules/musicbrainzapi.api.lyrics.concrete_builder.rst @@ -0,0 +1,10 @@ +.. include:: ../global.rst + +musicbrainzapi.api.lyrics.concrete_builder :modname:`musicbrainzapi.api.lyrics.concrete_builder` +------------------------------------------------------------------------------------------------- + +.. automodule:: musicbrainzapi.api.lyrics.concrete_builder + :members: + :undoc-members: + :show-inheritance: + :private-members: diff --git a/docs/source/modules/musicbrainzapi.api.lyrics.director.rst b/docs/source/modules/musicbrainzapi.api.lyrics.director.rst new file mode 100644 index 0000000..bdce62d --- /dev/null +++ b/docs/source/modules/musicbrainzapi.api.lyrics.director.rst @@ -0,0 +1,10 @@ +.. include:: ../global.rst + +musicbrainzapi.api.lyrics.director :modname:`musicbrainzapi.api.lyrics.director` +---------------------------------------------------------------------------------- + +.. automodule:: musicbrainzapi.api.lyrics.director + :members: + :undoc-members: + :show-inheritance: + :private-members: diff --git a/docs/source/modules/musicbrainzapi.api.lyrics.rst b/docs/source/modules/musicbrainzapi.api.lyrics.rst new file mode 100644 index 0000000..71a8c01 --- /dev/null +++ b/docs/source/modules/musicbrainzapi.api.lyrics.rst @@ -0,0 +1,16 @@ +.. include:: ../global.rst + +musicbrainzapi.api.lyrics :modname:`musicbrainzapi.api.lyrics` +-------------------------------------------------------------------------- + +.. automodule:: musicbrainzapi.api.lyrics + :members: + :undoc-members: + :show-inheritance: + :private-members: + +.. toctree:: + + musicbrainzapi.api.lyrics.builder + musicbrainzapi.api.lyrics.concrete_builder + musicbrainzapi.api.lyrics.director diff --git a/docs/source/modules/musicbrainzapi.api.rst b/docs/source/modules/musicbrainzapi.api.rst new file mode 100644 index 0000000..c3d3ebe --- /dev/null +++ b/docs/source/modules/musicbrainzapi.api.rst @@ -0,0 +1,19 @@ +.. include:: ../global.rst + +musicbrainzapi.api :modname:`musicbrainzapi.api` +-------------------------------------------------------------------------- + +.. automodule:: musicbrainzapi.api + :members: + :undoc-members: + :show-inheritance: + :private-members: + + +.. toctree:: + + musicbrainzapi.api.lyrics + +.. toctree:: + + musicbrainzapi.api.authenticate diff --git a/docs/source/modules/musicbrainzapi.cli.cli.rst b/docs/source/modules/musicbrainzapi.cli.cli.rst new file mode 100644 index 0000000..9b6e813 --- /dev/null +++ b/docs/source/modules/musicbrainzapi.cli.cli.rst @@ -0,0 +1,10 @@ +.. include:: ../global.rst + +musicbrainzapi.cli.cli :modname:`musicbrainzapi.cli.cli` +-------------------------------------------------------------------------- + +.. automodule:: musicbrainzapi.cli.cli + :members: + :undoc-members: + :show-inheritance: + :private-members: diff --git a/docs/source/modules/musicbrainzapi.cli.commands.cmd_lyrics.rst b/docs/source/modules/musicbrainzapi.cli.commands.cmd_lyrics.rst new file mode 100644 index 0000000..86946a1 --- /dev/null +++ b/docs/source/modules/musicbrainzapi.cli.commands.cmd_lyrics.rst @@ -0,0 +1,16 @@ +.. include:: ../global.rst + +musicbrainzapi.cli.commands.cmd_lyrics :modname:`musicbrainzapi.cli.commands.cmd_lyrics` +------------------------------------------------------------------------------------------ + +.. automodule:: musicbrainzapi.cli.commands.cmd_lyrics + :members: + :undoc-members: + :show-inheritance: + :private-members: + +lyrics subcommand. Use with... + +.. click:: musicbrainzapi.cli.cli:cli + :prog: musicbrainzapi + :show-nested: diff --git a/docs/source/modules/musicbrainzapi.cli.commands.rst b/docs/source/modules/musicbrainzapi.cli.commands.rst new file mode 100644 index 0000000..5dce26c --- /dev/null +++ b/docs/source/modules/musicbrainzapi.cli.commands.rst @@ -0,0 +1,14 @@ +.. include:: ../global.rst + +musicbrainzapi.cli.commands :modname:`musicbrainzapi.cli.commands` +-------------------------------------------------------------------------- + +.. automodule:: musicbrainzapi.cli.commands + :members: + :undoc-members: + :show-inheritance: + :private-members: + +.. toctree:: + + musicbrainzapi.cli.commands.cmd_lyrics diff --git a/docs/source/modules/musicbrainzapi.cli.rst b/docs/source/modules/musicbrainzapi.cli.rst new file mode 100644 index 0000000..c3f2276 --- /dev/null +++ b/docs/source/modules/musicbrainzapi.cli.rst @@ -0,0 +1,18 @@ +.. include:: ../global.rst + +musicbrainzapi.cli :modname:`musicbrainzapi.cli` +-------------------------------------------------------------------------- + +.. automodule:: musicbrainzapi.cli + :members: + :undoc-members: + :show-inheritance: + :private-members: + +.. toctree:: + + musicbrainzapi.cli.commands + +.. toctree:: + + musicbrainzapi.cli.cli diff --git a/docs/source/modules/musicbrainzapi.rst b/docs/source/modules/musicbrainzapi.rst new file mode 100644 index 0000000..3148c84 --- /dev/null +++ b/docs/source/modules/musicbrainzapi.rst @@ -0,0 +1,12 @@ +.. include:: ../global.rst + +musicbrainzapi :modname:`musicbrainzapi` +----------------------------------------- + +.. automodule:: musicbrainzapi + :members: + :undoc-members: + :show-inheritance: + :private-members: + +Main module text diff --git a/docs/source/modules/musicbrainzapi.wordcloud.resources.rst b/docs/source/modules/musicbrainzapi.wordcloud.resources.rst new file mode 100644 index 0000000..8a64ee0 --- /dev/null +++ b/docs/source/modules/musicbrainzapi.wordcloud.resources.rst @@ -0,0 +1,10 @@ +.. include:: ../global.rst + +musicbrainzapi.wordcloud.resources :modname:`musicbrainzapi.wordcloud.resources` +--------------------------------------------------------------------------------- + +.. automodule:: musicbrainzapi.wordcloud.resources + :members: + :undoc-members: + :show-inheritance: + :private-members: diff --git a/docs/source/modules/musicbrainzapi.wordcloud.rst b/docs/source/modules/musicbrainzapi.wordcloud.rst new file mode 100644 index 0000000..9c42b3d --- /dev/null +++ b/docs/source/modules/musicbrainzapi.wordcloud.rst @@ -0,0 +1,14 @@ +.. include:: ../global.rst + +musicbrainzapi.wordcloud :modname:`musicbrainzapi.wordcloud` +-------------------------------------------------------------------------- + +.. automodule:: musicbrainzapi.wordcloud + :members: + :undoc-members: + :show-inheritance: + :private-members: + +.. toctree:: + + musicbrainzapi.wordcloud.resources diff --git a/docs/source/toc.rst b/docs/source/toc.rst new file mode 100644 index 0000000..e4796b1 --- /dev/null +++ b/docs/source/toc.rst @@ -0,0 +1,23 @@ +.. toctree:: + :maxdepth: 1 + :caption: Overview + :titlesonly: + + introduction + changelog + +.. toctree:: + :maxdepth: 4 + :caption: Modules + :titlesonly: + + modules/musicbrainzapi.rst + +.. toctree:: + :maxdepth: 4 + :caption: Submodules + :titlesonly: + + modules/musicbrainzapi.api.rst + modules/musicbrainzapi.cli.rst + modules/musicbrainzapi.wordcloud.rst