Add structure and pages to sphinx (neuralmagic#27)

* Add structure and pages to sphinx doc generation

* update links

* small fixes

* small fixes

* update copyright for rst files

* update sphinx dev dep

Author: markurtz

.gitignore

@@ -1,4 +1,4 @@
-*.rst
+/docs/source/api/*.rst
 
 # Created by https://www.toptal.com/developers/gitignore/api/windows,macos,linux,python,react,pycharm,emacs,vim,visualstudio,visualstudiocode
 # Edit at https://www.toptal.com/developers/gitignore?templates=windows,macos,linux,python,react,pycharm,emacs,vim,visualstudio,visualstudiocode

Makefile

@@ -4,7 +4,7 @@ BUILDDIR := $(PWD)
 PYCHECKDIRS := examples tests src utils scripts notebooks
 PYCHECKGLOBS := 'examples/**/*.py' 'scripts/**/*.py' 'src/**/*.py' 'tests/**/*.py' 'utils/**/*.py' setup.py
 DOCDIR := docs
-MDCHECKGLOBS := 'docs/**/*.md' 'examples/**/*.md' 'notebooks/**/*.md' 'scripts/**/*.md'
+MDCHECKGLOBS := 'docs/**/*.md' 'docs/**/*.rst' 'examples/**/*.md' 'notebooks/**/*.md' 'scripts/**/*.md'
 MDCHECKFILES := CODE_OF_CONDUCT.md CONTRIBUTING.md DEVELOPING.md README.md
 
 # run checks on all files for the repo
@@ -31,7 +31,7 @@ test:
 
 # create docs
 docs:
-	sphinx-apidoc -o "$(DOCDIR)/source/" src/sparsezoo;
+	sphinx-apidoc -o "$(DOCDIR)/source/api" src/sparsezoo;
 	cd $(DOCDIR) && $(MAKE) html;
 
 # creates wheel file

README.md

@@ -194,7 +194,7 @@ sparsezoo download --domain cv --sub-domain classification \
 
 For a more in-depth read, check out [SparseZoo documentation](https://docs.neuralmagic.com/sparsezoo/).
 
-### Installation
+## Installation
 
 This repository is tested on Python 3.6+, and Linux/Debian systems.
 It is recommended to install in a [virtual environment](https://docs.python.org/3/library/venv.html) to keep your system in order.

docs/available-models.md

@@ -18,12 +18,15 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "sparsezoo"
-copyright = "2020, Neural Magic"
+project = "Sparse Zoo"
+copyright = (
+    "Copyright (c) 2021 - present / Neuralmagic, Inc. All Rights Reserved. "
+    'Licensed under the Apache License, Version 2.0 (the "License")'
+)
 author = "Neural Magic"
 
 # The full version, including alpha/beta/rc tags
-version = ""
+version = "0.1"
 release = "0.1.0"
 
 
@@ -34,12 +37,17 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.intersphinx",
+    "sphinx.ext.coverage",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.githubpages",
     "sphinx.ext.ifconfig",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
-    "sphinx.ext.githubpages",
-    "rinoh.frontend.sphinx",
+    "sphinx_copybutton",
+    "sphinx_markdown_tables",
     "sphinx_rtd_theme",
+    "recommonmark",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -48,11 +56,11 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
+# source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = "sparsezoo"
+master_doc = "index"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -76,6 +84,7 @@
 # a list of builtin themes.
 #
 html_theme = "sphinx_rtd_theme"
+html_logo = "icon-sparsezoo.png"
 
 # 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,
@@ -92,39 +101,35 @@
 #
 # html_sidebars = {}
 
+html_favicon = "favicon.ico"
+
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "neuralmagicMLdoc"
+htmlhelp_basename = "sparsezoodoc"
 
 
 # -- Options for LaTeX output ------------------------------------------------
 
 latex_elements = {
-    "papersize": "letterpaper",
-    "pointsize": "10pt",
-    "preamble": "",
-    "figure_align": "htbp",
+    # "papersize": "letterpaper",
+    # "pointsize": "10pt",
+    # "preamble": "",
+    # "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,
-        "SparseZoo_API.tex",
-        "Sparse Zoo API",
-        "Neural Magic",
-        "manual",
-    ),
+    (master_doc, "sparsezoo.tex", "Sparse Zoo Documentation", [author], "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, "sparsezooapi", "Sparse Zoo API Documentation", [author], 1)]
+man_pages = [(master_doc, "sparsezoo", "Sparse Zoo Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output ----------------------------------------------
@@ -135,11 +140,14 @@
 texinfo_documents = [
     (
         master_doc,
-        "",
-        "Sparse Zoo API Documentation",
+        "sparsezoo",
+        "Sparse Zoo Documentation",
         author,
-        "SparseZoo_API",
-        "API implementations designed for Sparse Zoo.",
+        "sparsezoo",
+        (
+            "Neural network model repository for highly sparse "
+            "models and optimization recipes"
+        ),
         "Miscellaneous",
     ),
 ]
@@ -163,7 +171,7 @@
 # epub_uid = ''
 
 # A list of files that should not be packed into the epub file.
-epub_exclude_files = ["search.html"]
+epub_exclude_files = []
 
 
 # -- Extension configuration -------------------------------------------------

docs/.gitkeep docs/source/api/.gitkeep

@@ -0,0 +1,111 @@
+..
+    Copyright (c) 2021 - present / Neuralmagic, Inc. All Rights Reserved.
+    
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+    
+       http://www.apache.org/licenses/LICENSE-2.0
+    
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+===================
+SparseZoo |version|
+===================
+
+Neural network model repository for highly sparse models and optimization recipes.
+
+.. raw:: html
+
+    <div style="margin-bottom:16px;">
+        <a href="https://github.com/neuralmagic/sparsezoo/blob/master/LICENSE">
+            <img alt="GitHub" src="https://img.shields.io/github/license/neuralmagic/sparsezoo.svg?color=purple&style=for-the-badge" height=25 style="margin-bottom:4px;">
+        </a>
+        <a href="https://docs.neuralmagic.com/sparsezoo/index.html">
+            <img alt="Documentation" src="https://img.shields.io/website/http/neuralmagic.com/sparsezoo/index.html.svg?down_color=red&down_message=offline&up_message=online&style=for-the-badge" height=25 style="margin-bottom:4px;">
+        </a>
+        <a href="https://github.com/neuralmagic/sparsezoo/releases">
+            <img alt="GitHub release" src="https://img.shields.io/github/release/neuralmagic/sparsezoo.svg?style=for-the-badge" height=25 style="margin-bottom:4px;">
+        </a>
+        <a href="https://github.com/neuralmagic.com/sparsezoo/blob/master/CODE_OF_CONDUCT.md">
+            <img alt="Contributor Covenant" src="https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg?color=yellow&style=for-the-badge" height=25 style="margin-bottom:4px;">
+        </a>
+         <a href="https://www.youtube.com/channel/UCo8dO_WMGYbWCRnj_Dxr4EA">
+            <img src="https://img.shields.io/badge/-YouTube-red?&style=for-the-badge&logo=youtube&logoColor=white" height=25 style="margin-bottom:4px;">
+        </a>
+         <a href="https://medium.com/limitlessai">
+            <img src="https://img.shields.io/badge/medium-%2312100E.svg?&style=for-the-badge&logo=medium&logoColor=white" height=25 style="margin-bottom:4px;">
+        </a>
+        <a href="https://twitter.com/neuralmagic">
+            <img src="https://img.shields.io/twitter/follow/neuralmagic?color=darkgreen&label=Follow&style=social" height=25 style="margin-bottom:4px;">
+        </a>
+     </div>
+
+Overview
+========
+
+SparseZoo is a constantly-growing repository of optimized models and optimization recipes for neural networks.
+It simplifies and accelerates your time-to-value in building performant deep learning models with a
+collection of inference-optimized models and recipes to prototype from.
+
+Available via API and hosted in the cloud, the SparseZoo contains both baseline and models optimized
+to different degrees of inference performance vs baseline loss recovery.
+Optimizations on neural networks include approaches such as
+`pruning <https://neuralmagic.com/blog/pruning-overview />`_ and `quantization <https://arxiv.org/abs/1609.07061 />`_
+allowing for significantly faster models with limited to no effect on their baseline metrics such as accuracy.
+Recipe-driven approaches built around these optimizations allow you to take the models as given,
+transfer learn from the models onto private datasets, or transfer the recipes to your architectures.
+
+This repository contains the Python API code to handle the connection and authentication to the cloud.
+
+Related Products
+================
+
+- `DeepSparse <https://github.com/neuralmagic/deepsparse />`_:
+  CPU inference engine that delivers unprecedented performance for sparse models
+- `SparseML <https://github.com/neuralmagic/sparseml />`_:
+  Libraries for state-of-the-art deep neural network optimization algorithms,
+  enabling simple pipelines integration with a few lines of code
+- `Sparsify <https://github.com/neuralmagic/sparsify />`_:
+  Easy-to-use autoML interface to optimize deep neural networks for
+  better inference performance and a smaller footprint
+
+Resources and Learning More
+===========================
+
+- `SparseZoo Documentation <https://docs.neuralmagic.com/sparsezoo/ />`_
+- `SparseML Documentation <https://docs.neuralmagic.com/sparseml/ />`_
+- `Sparsify Documentation <https://docs.neuralmagic.com/sparsify/ />`_
+- `DeepSparse Documentation <https://docs.neuralmagic.com/deepsparse/ />`_
+- `Neural Magic Blog <https://www.neuralmagic.com/blog/ />`_,
+  `Resources <https://www.neuralmagic.com/resources/ />`_,
+  `Website <https://www.neuralmagic.com/ />`_
+
+Release History
+===============
+
+Official builds are hosted on PyPi
+- stable: `sparsezoo <https://pypi.org/project/sparsezoo/ />`_
+- nightly (dev): `sparsezoo-nightly <https://pypi.org/project/sparsezoo-nightly/ />`_
+
+Additionally, more information can be found via
+`GitHub Releases <https://github.com/neuralmagic/sparsezoo/releases />`_.
+
+.. toctree::
+    :maxdepth: 3
+    :caption: General
+
+    quicktour
+    installation
+    models
+    recipes
+
+.. toctree::
+    :maxdepth: 2
+    :caption: API
+
+    api/sparsezoo

docs/source/conf.py

@@ -0,0 +1,32 @@
+<!--
+Copyright (c) 2021 - present / Neuralmagic, Inc. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+### Installation
+
+This repository is tested on Python 3.6+, and Linux/Debian systems.
+It is recommended to install in a [virtual environment](https://docs.python.org/3/library/venv.html) 
+to keep your system in order.
+
+Install with pip using:
+
+```bash
+pip install sparsezoo
+```
+
+Then if you would like to explore any of the [scripts](https://github.com/neuralmagic/sparsezoo/tree/main/scripts), 
+[notebooks](https://github.com/neuralmagic/sparsezoo/tree/main/notebooks), 
+or [examples](https://github.com/neuralmagic/sparsezoo/tree/main/examples)
+clone the repository and install any additional dependencies as required.