Added Sphinx doc generation

.circleci/config.yml

@@ -2,7 +2,7 @@ version: 2.1
 orbs:
   codecov: codecov/codecov@1.0.5
 jobs:
-  build:
+  pkg-build:
     docker:
       - image: circleci/python:3.6.1
 
@@ -11,12 +11,11 @@ jobs:
     steps:
       - checkout
 
-      # Cached build dependencies
+      # Cached installation dependencies
       - restore_cache:
           keys:
-            - requirements-{{ .Branch }}-{{ checksum "requirements.txt" }}
-            - requirements-{{ .Branch }}
-            - requirements
+            - v1-dependencies-{{ .Branch }}-{{ checksum "requirements.txt" }}
+            - v1-dependencies-{{ .Branch }}
 
       - run:
           name: Package installation
@@ -29,9 +28,9 @@ jobs:
       - save_cache:
           paths:
             - ./venv
-          key: requirements-{{ .Branch }}-{{ checksum "requirements.txt" }}
+          key: v1-dependencies-{{ .Branch }}-{{ checksum "requirements.txt" }}
 
-  test:
+  pkg-test:
     docker:
       - image: circleci/python:3.6.1
 
@@ -43,10 +42,9 @@ jobs:
       # Cached test dependencies
       - restore_cache:
           keys:
-            - requirements-{{ .Branch }}-{{ checksum "requirements.txt" }}-{{ checksum ".circleci/requirements.txt" }}
-            - requirements-{{ .Branch }}-{{ checksum "requirements.txt" }}
-            - requirements-{{ .Branch }}
-            - requirements
+            - v1-dependencies-{{ .Branch }}-{{ checksum "requirements.txt" }}-{{ checksum ".circleci/requirements.txt" }}
+            - v1-dependencies-{{ .Branch }}-{{ checksum "requirements.txt" }}
+            - v1-dependencies-{{ .Branch }}
 
       - run:
           name: CI dependencies installation
@@ -61,7 +59,7 @@ jobs:
           when: always
           paths:
             - "venv"
-          key: requirements-{{ .Branch }}-{{ checksum "requirements.txt" }}-{{ checksum ".circleci/requirements.txt" }}
+          key: v1-dependencies-{{ .Branch }}-{{ checksum "requirements.txt" }}-{{ checksum ".circleci/requirements.txt" }}
 
       - run:
           name: Package unit tests
@@ -73,12 +71,76 @@ jobs:
       - codecov/upload:
           file: coverage.xml
           flags: unittests
+  docs-build:
+    docker:
+      - image: python:3.7
+    steps:
+      - checkout
+
+      # Cached doc dependencies
+      - restore_cache:
+          keys:
+            - v1-dependencies-{{ .Branch }}-{{ checksum "requirements.txt" }}-{{ checksum "docs/requirements.txt" }}
+            - v1-dependencies-{{ .Branch }}-{{ checksum "requirements.txt" }}
+            - v1-dependencies-{{ .Branch }}
+
+      - run:
+          name: Install dependencies
+          command: |
+            python3 -m venv venv
+            . venv/bin/activate
+            python -m pip install --upgrade pip
+            pip install -e .
+            pip install -r docs/requirements.txt
+
+      - save_cache:
+          when: always
+          paths:
+            - "venv"
+          key: v1-dependencies-{{ .Branch }}-{{ checksum "requirements.txt" }}-{{ checksum "docs/requirements.txt" }}
+      - run:
+          name: Build docs
+          command: |
+            . venv/bin/activate
+            sphinx-build docs/source docs/build -a
+      - persist_to_workspace:
+          root: docs/build
+          paths: .
+  docs-deploy:
+    docker:
+      - image: node:8.10.0
+    steps:
+      - checkout
+      - attach_workspace:
+          at: docs/build
+      - run:
+          name: Disable jekyll builds
+          command: touch docs/build/.nojekyll
+      - run:
+          name: Install and configure dependencies
+          command: |
+            npm install -g --silent gh-pages@2.0.1
+            git config user.email "fgfm03@hotmail.fr"
+            git config user.name "frgfm"
+      - run:
+          name: Deploy docs to gh-pages branch
+          command: gh-pages --dotfiles --message "[skip ci] Updates" --dist docs/build
 
 workflows:
   version: 2.1
-  build_and_test:
+  build:
     jobs:
-      - build
-      - test:
+      - pkg-build
+      - docs-build:
+          requires:
+            - pkg-build
+      - pkg-test:
+          requires:
+            - pkg-build
+      - docs-deploy:
           requires:
-            - build
+            - pkg-build
+            - docs-build
+          filters:
+            branches:
+              only: master

README.md

@@ -1,13 +1,15 @@
 # Holocron
 
-[![Donate](https://img.shields.io/badge/License-MIT-brightgreen.svg)](LICENSE) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/5713eafaf8074e27a4013dbfcfad9d69)](https://www.codacy.com/manual/fg/Holocron?utm_source=github.com&utm_medium=referral&utm_content=frgfm/Holocron&utm_campaign=Badge_Grade) [![CircleCI](https://circleci.com/gh/frgfm/Holocron.svg?style=shield)](https://circleci.com/gh/frgfm/Holocron) [![codecov](https://codecov.io/gh/frgfm/Holocron/branch/master/graph/badge.svg)](https://codecov.io/gh/frgfm/Holocron)
+[![License](https://img.shields.io/badge/License-MIT-brightgreen.svg)](LICENSE) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/5713eafaf8074e27a4013dbfcfad9d69)](https://www.codacy.com/manual/fg/Holocron?utm_source=github.com&utm_medium=referral&utm_content=frgfm/Holocron&utm_campaign=Badge_Grade) [![CircleCI](https://circleci.com/gh/frgfm/Holocron.svg?style=shield)](https://circleci.com/gh/frgfm/Holocron) [![codecov](https://codecov.io/gh/frgfm/Holocron/branch/master/graph/badge.svg)](https://codecov.io/gh/frgfm/Holocron)[![Docs](https://img.shields.io/badge/docs-available-blue.svg)](https://frgfm.github.io/Holocron)
 
 Implementations of recent Deep Learning tricks in Computer Vision, easily paired up with your favorite framework and model zoo.
 
 > **Holocrons** were information-storage [datacron](https://starwars.fandom.com/wiki/Datacron) devices used by both the [Jedi Order](https://starwars.fandom.com/wiki/Jedi_Order) and the [Sith](https://starwars.fandom.com/wiki/Sith) that contained ancient lessons or valuable information in [holographic](https://starwars.fandom.com/wiki/Hologram) form.
 
 *Source: Wookieepedia*
 
+
+
 ## Installation
 
 This package was developed using minimal dependencies ([pytorch](https://github.com/pytorch/pytorch), [torchvision](https://github.com/pytorch/vision)). 
@@ -25,7 +27,9 @@ git clone https://github.com/frgfm/Holocron.git
 pip install -e Holocron/
 ```
 
-## Modules
+
+
+## Usage
 
 ### nn
 
@@ -227,6 +231,12 @@ plt.imshow(result); plt.axis('off'); plt.title(classes.get(class_idx)); plt.tigh
 
 
 
+## Documentation
+
+The full package documentation is available [here](<https://frgfm.github.io/Holocron/>) for detailed specifications.
+
+
+
 ## Submitting a request / Reporting an issue
 
 Regarding issues, use the following format for the title:

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)

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

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+-e git://github.com/snide/sphinx_rtd_theme.git#egg=sphinx_rtd_theme