diff --git a/.bumpversion.cfg b/.bumpversion.cfg index ea6e990..2c978b8 100644 --- a/.bumpversion.cfg +++ b/.bumpversion.cfg @@ -3,19 +3,20 @@ current_version = 0.1.1-rc0 commit = True tag = True parse = (?P\d+)\.(?P\d+)\.(?P\d+)(\-(?P[a-z]+)(?P\d+))? -serialize = - {major}.{minor}.{patch}-{release}{build} - {major}.{minor}.{patch} +serialize = + {major}.{minor}.{patch}-{release}{build} + {major}.{minor}.{patch} [bumpversion:part:release] optional_value = prod first_value = dev -values = - dev - rc - prod +values = + dev + rc + prod [bumpversion:file:setup.py] [bumpversion:file:./prototorch/__init__.py] +[bumpversion:file:./docs/source/conf.py] diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..899dcd6 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,27 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/source/conf.py + fail_on_warning: true + +# Build documentation with MkDocs +# mkdocs: +# configuration: mkdocs.yml + +# Optionally build your docs in additional formats such as PDF and ePub +formats: all + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.8 + install: + - method: pip + path: . + extra_requirements: + - all diff --git a/README.md b/README.md index d456256..6635c1b 100644 --- a/README.md +++ b/README.md @@ -45,22 +45,8 @@ pip install -e .[all] ## Documentation -The documentation is available at - -## Usage - -### For researchers -ProtoTorch is modular. It is very easy to use the modular pieces provided by -ProtoTorch, like the layers, losses, callbacks and metrics to build your own -prototype-based(instance-based) models. These pieces blend-in seamlessly with -Keras allowing you to mix and match the modules from ProtoFlow with other -modules in `torch.nn`. - -### For engineers -ProtoTorch comes prepackaged with many popular Learning Vector Quantization -(LVQ)-like algorithms in a convenient API. If you would simply like to be able -to use those algorithms to train large ML models on a GPU, ProtoTorch lets you -do this without requiring a black-belt in high-performance Tensor computing. +The documentation is available at . Should +that link not work try . ## Bibtex diff --git a/RELEASE.md b/RELEASE.md index 09ae177..80bebfd 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,5 +1,10 @@ # ProtoTorch Releases +## Release 0.2.0 + +### Includes +- Fixes in example scripts. + ## Release 0.1.1-dev0 ### Includes diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..61ebf92 --- /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 ?= python3 -m sphinx +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..6cfef6c --- /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/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..c0d4375 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +torch==1.6.0 +matplotlib==3.1.2 +sphinx_rtd_theme==0.5.0 +sphinxcontrib-katex==0.6.1 diff --git a/docs/source/_static/img/horizontal-lockup.png b/docs/source/_static/img/horizontal-lockup.png new file mode 100644 index 0000000..9e88826 Binary files /dev/null and b/docs/source/_static/img/horizontal-lockup.png differ diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..9f37ddb --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,28 @@ +.. ProtoFlow API Reference + +ProtoFlow API Reference +====================================== + +Datasets +-------------------------------------- +.. automodule:: prototorch.datasets + :members: + :undoc-members: + +Functions +-------------------------------------- +.. automodule:: prototorch.functions + :members: + :undoc-members: + +Modules +-------------------------------------- +.. automodule:: prototorch.modules + :members: + :undoc-members: + +Utilities +-------------------------------------- +.. automodule:: prototorch.utils + :members: + :undoc-members: diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..66bf429 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,180 @@ +# 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 sphinx_rtd_theme + +# -- Project information ----------------------------------------------------- + +project = "ProtoTorch" +copyright = "2021, Jensun Ravichandran" +author = "Jensun Ravichandran" + +# The full version, including alpha/beta/rc tags +# +release = "0.1.1-rc0" + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +needs_sphinx = "1.6" + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named "sphinx.ext.*") or your custom +# ones. +extensions = [ + "recommonmark", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.doctest", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.coverage", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx_rtd_theme", + "sphinxcontrib.katex", +] + +# katex_prerender = True +katex_prerender = False + +napoleon_use_ivar = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +source_suffix = [".rst", ".md"] + +# 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 = [] + +# The name of the Pygments (syntax highlighting) style to use. Choose from: +# ["default", "emacs", "friendly", "colorful", "autumn", "murphy", "manni", +# "monokai", "perldoc", "pastie", "borland", "trac", "native", "fruity", "bw", +# "vim", "vs", "tango", "rrt", "xcode", "igor", "paraiso-light", "paraiso-dark", +# "lovelace", "algol", "algol_nu", "arduino", "rainbo w_dash", "abap", +# "solarized-dark", "solarized-light", "sas", "stata", "stata-light", +# "stata-dark", "inkpot"] +pygments_style = "monokai" + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + +# Disable docstring inheritance +autodoc_inherit_docstrings = False + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# https://sphinx-themes.org/ +html_theme = "sphinx_rtd_theme" + +html_logo = "_static/img/horizontal-lockup.png" + +html_theme_options = { + "logo_only": True, + "display_version": True, + "prev_next_buttons_location": "bottom", + "style_external_links": False, + "style_nav_header_background": "#ffffff", + # Toc options + "collapse_navigation": True, + "sticky_navigation": True, + "navigation_depth": 4, + "includehidden": True, + "titles_only": False, +} + +# 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"] + +html_css_files = [ + "https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css", +] + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = "protoflowdoc" + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ("letterpaper" or "a4paper"). + # + # "papersize": "letterpaper", + + # The font size ("10pt", "11pt" or "12pt"). + # + # "pointsize": "10pt", + + # Additional stuff for the LaTeX preamble. + # + # "preamble": "", + + # Latex figure (float) alignment + # + # "figure_align": "htbp", +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, "prototorch.tex", "ProtoTorch Documentation", + "Jensun Ravichandran", "manual"), +] + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "ProtoTorch", "ProtoTorch Documentation", [author], 1)] + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, "prototorch", "ProtoTorch Documentation", author, "prototorch", + "Prototype-based machine learning in PyTorch.", + "Miscellaneous"), +] + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + "python": ("https://docs.python.org/", None), + "numpy": ("https://docs.scipy.org/doc/numpy/", None), +} + +# -- Options for Epub output ---------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-epub-output + +epub_cover = () +version = release diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..473a71f --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,22 @@ +.. ProtoTorch documentation master file + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +About ProtoTorch +================ + +.. toctree:: + :hidden: + :maxdepth: 3 + :caption: Contents: + + self + api + +ProtoTorch is a PyTorch-based Python toolbox for bleeding-edge +research in prototype-based machine learning algorithms. + +Indices +======= +* :ref:`genindex` +* :ref:`modindex` diff --git a/prototorch/modules/prototypes.py b/prototorch/modules/prototypes.py index 78d9349..3d98dd8 100644 --- a/prototorch/modules/prototypes.py +++ b/prototorch/modules/prototypes.py @@ -25,40 +25,9 @@ class _Prototypes(torch.nn.Module): class Prototypes1D(_Prototypes): - r"""Create a learnable set of one-dimensional prototypes. + """Create a learnable set of one-dimensional prototypes. - TODO Complete this doc-string - - Kwargs: - prototypes_per_class: number of prototypes to use per class. - Default: ``1`` - prototype_initializer: prototype initializer. - Default: ``'ones'`` - prototype_distribution: prototype distribution vector. - Default: ``None`` - input_dim: dimension of the incoming data. - nclasses: number of classes. - data: If set to ``None``, data-dependent initializers will be ignored. - Default: ``None`` - - Shape: - - Input: :math:`(N, H_{in})` - where :math:`H_{in} = \text{input_dim}`. - - Output: :math:`(N, H_{out})` - where :math:`H_{out} = \text{total_prototypes}`. - - Attributes: - prototypes: the learnable weights of the module of shape - :math:`(\text{total_prototypes}, \text{prototype_dimension})`. - prototype_labels: the non-learnable labels of the prototypes. - - Examples: - - >>> p = Prototypes1D(input_dim=20, nclasses=10) - >>> input = torch.randn(128, 20) - >>> output = m(input) - >>> print(output.size()) - torch.Size([20, 10]) + TODO Complete this doc-string. """ def __init__(self, prototypes_per_class=1,