Add structure and pages to sphinx (#52)

Author: markurtz

.gitignore

@@ -20,7 +20,7 @@ tensorboard/*
 onnx/*
 repos/*
 
-*.rst
+/docs/source/api/*.rst
 
 ### Python template
 # Byte-compiled / optimized / DLL files

Makefile

@@ -4,7 +4,7 @@ BUILDDIR := $(PWD)
 CHECKDIRS := examples notebooks scripts src tests utils setup.py
 CHECKGLOBS := '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
 
 TARGETS := ""  # targets for running pytests: keras,onnx,pytorch,pytorch_models,pytorch_datasets,tensorflow_v1,tensorflow_v1_models,tensorflow_v1_datasets
@@ -58,8 +58,8 @@ test:
 
 # create docs
 docs:
-	sphinx-apidoc -o "$(DOCDIR)/source/" src/sparseml;
-	cd $(DOCDIR) && $(MAKE) html;
+	export SPARSEML_IGNORE_TFV1="True"; sphinx-apidoc -o "$(DOCDIR)/source/api/" src/sparseml;
+	export SPARSEML_IGNORE_TFV1="True"; cd $(DOCDIR) && $(MAKE) html;
 
 # creates wheel file
 build:

docs/README.md

@@ -18,13 +18,16 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "sparseml"
-copyright = "2020, Neural Magic"
+project = "SparseML"
+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 = ""
-release = "1.0.9"
+version = "0.1"
+release = "0.1.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -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 = "sparseml"
+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-sparseml.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 = "sparseMLdoc"
+htmlhelp_basename = "sparsemldoc"
 
 
 # -- 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,
-        "SparseML_API.tex",
-        "SparseML API",
-        "Neural Magic",
-        "manual",
-    ),
+    (master_doc, "sparseml.tex", "SparseML 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, "sparsemlapi", "SparseML API Documentation", [author], 1)]
+man_pages = [(master_doc, "sparseml", "SparseML Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output ----------------------------------------------
@@ -135,11 +140,14 @@
 texinfo_documents = [
     (
         master_doc,
-        "",
-        "SparseML API Documentation",
+        "sparseml",
+        "SparseML Documentation",
         author,
-        "SparseML_API",
-        "API implementations designed for ML frameworks to enable better performance in the Neural Magic system.",
+        "sparseml",
+        (
+            "Libraries for state-of-the-art deep neural network optimization "
+            "algorithms, enabling simple pipelines integration with a few lines of code"
+        ),
         "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/source/api/.gitkeep

@@ -0,0 +1,105 @@
+..
+    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.
+
+===================
+SparseML |version|
+===================
+
+Libraries for state-of-the-art deep neural network optimization algorithms,
+enabling simple pipelines integration with a few lines of code
+
+.. raw:: html
+
+    <div style="margin-bottom:16px;">
+        <a href="https://github.com/neuralmagic/sparseml/blob/master/LICENSE">
+            <img alt="GitHub" src="https://img.shields.io/github/license/neuralmagic/sparseml.svg?color=purple&style=for-the-badge" height=25 style="margin-bottom:4px;">
+        </a>
+        <a href="https://docs.neuralmagic.com/sparseml/index.html">
+            <img alt="Documentation" src="https://img.shields.io/website/http/neuralmagic.com/sparseml/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/sparseml/releases">
+            <img alt="GitHub release" src="https://img.shields.io/github/release/neuralmagic/sparseml.svg?style=for-the-badge" height=25 style="margin-bottom:4px;">
+        </a>
+        <a href="https://github.com/neuralmagic.com/sparseml/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
+========
+
+SparseML is a toolkit that includes APIs, CLIs, scripts and libraries that apply state-of-the-art optimization
+algorithms such as `pruning <https://neuralmagic.com/blog/pruning-overview/ />`_ and
+`quantization <https://arxiv.org/abs/1609.07061 />`_ to any neural network.
+General, recipe-driven approaches built around these optimizations enable the simplification of creating faster
+and smaller models for the ML performance community at large.
+
+SparseML is integrated for easy model optimizations within the `PyTorch <https://pytorch.org/ />`_,
+`Keras <https://keras.io/ />`_, and `TensorFlow V1 <http://tensorflow.org/ />`_ ecosystems currently.
+
+Related Products
+================
+
+- `DeepSparse <https://github.com/neuralmagic/deepsparse />`_:
+  CPU inference engine that delivers unprecedented performance for sparse models
+- `Sparse Zoo <https://github.com/neuralmagic/sparsezoo />`_:
+  Neural network model repository for highly sparse models and optimization recipes
+- `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/sparseml/ />`_
+- nightly (dev): `sparsezoo-nightly <https://pypi.org/project/sparseml-nightly/ />`_
+
+Additionally, more information can be found via
+`GitHub Releases <https://github.com/neuralmagic/sparseml/releases />`_.
+
+.. toctree::
+    :maxdepth: 3
+    :caption: General
+
+    quicktour
+    installation
+    recipes
+
+.. toctree::
+    :maxdepth: 2
+    :caption: API
+
+    api/sparseml

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.