Fix the doc auto-build. (#53)

* Attempt to fix the doc build.

* Update requirements.txt

* Update setup.py

* Add YML config for readthedocs.

* Update ignore files and the packge setup file.

* Add files for sphinx-builders.

* Move the source files for sphinx around.

* Fix an issue with path that sphinx cannot find the main reademe file.

* Loosen one requirement.

.gitignore

@@ -3,6 +3,7 @@ __pycache__/
 *.py[cod]
 *$py.class
 *.idea
+.pytest_cache
 
 # C extensions
 *.so
@@ -60,6 +61,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/generated
 
 # PyBuilder
 target/

docs/README.md

@@ -1,16 +1,23 @@
 # Build Docs 
-from the repository root, type: 
+
+1. Make sure you have [Sphinx](http://www.sphinx-doc.org/en/stable/) installed.
+2. Install the sctools package in advance following the instructions.
+3. From the current directory (/docs/), type:
 
 ```bash
-sphinx-apidoc -f -o docs/source/ ./
-sphinx-apidoc -f -o docs/source/ src/sctools
-sphinx-build -b html docs/source/ docs/build/
+make target
 ```
+where `target` is one of {html, epub, latex, ...}. For more details about the sphinx builders, check [here](http://www.sphinx-doc.org/en/master/man/sphinx-build.html)
 
 Note that there are still some bugs to be worked out. 
-- `autosummary` is not a known directive
-- `modules.rst` is not included in any toctree
-- `setup` module cannot be imported
-- `sctools.rst` is not included in any toctree
-- /Users/ajc/projects/humancellatlas/sctools/src/sctools/reader.py:docstring of sctools.reader.zip_readers:: WARNING: more than one target found for cross-reference 'Reader': sctools.fastq.Reader, sctools.gtf.Reader, sctools.reader.Reader
-- there are a bunch of unexpected section titles
+- There are warnings about: 
+```
+WARNING: [autosummary] failed to import 'sctools.metrics.CellMetrics': no module named sctools.metrics.CellMetrics
+WARNING: [autosummary] failed to import 'sctools.metrics.GeneMetrics': no module named sctools.metrics.GeneMetrics
+WARNING: [autosummary] failed to import 'sctools.metrics.MetricAggregatorBase': no module named sctools.metrics.MetricAggregatorBase
+```
+
+- There are a bunch of warnings: `WARNING: Unexpected section title.`
+- There are a bunch of warnings: `WARNING: toctree contains reference to nonexisting document`
+
+Most of the warnings can be solved by refactoring the docstrings and standardize the usages of `autosummary` later.

docs/source/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = SCTools
+SOURCEDIR     = .
+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/source/conf.py

@@ -12,10 +12,10 @@
 # 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
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('..'))
 from pkg_resources import get_distribution
-sys.path.insert(0, os.path.abspath('..'))
 
 
 # -- Project information -----------------------------------------------------
@@ -44,7 +44,8 @@
     'sphinx.ext.doctest',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
-    'sphinxcontrib.napoleon',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.autosummary'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -69,7 +70,7 @@
 # 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 = []
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -162,3 +163,5 @@
 
 
 # -- Extension configuration -------------------------------------------------
+numpydoc_show_class_members = False
+autosummary_generate = True

docs/source/index.rst

@@ -0,0 +1,21 @@
+.. toctree::
+   :maxdepth: 1
+   :caption: Overview
+
+   readme
+
+.. toctree::
+   :maxdepth: 4
+   :caption: API References
+
+   sctools
+   sctools.metrics
+   sctools.test
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/readme.rst

@@ -0,0 +1 @@
+.. include:: ../../README.rst

docs/source/sctools.metrics.rst

@@ -0,0 +1,41 @@
+sctools.metrics package
+=======================
+
+Submodules
+~~~~~~~~~~
+
+sctools.metrics.aggregator module
+---------------------------------
+
+.. automodule:: sctools.metrics.aggregator
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
+sctools.metrics.gatherer module
+-------------------------------
+
+.. automodule:: sctools.metrics.gatherer
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
+sctools.metrics.merge module
+----------------------------
+
+.. automodule:: sctools.metrics.merge
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
+sctools.metrics.writer module
+-----------------------------
+
+.. automodule:: sctools.metrics.writer
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:

docs/source/sctools.rst

@@ -0,0 +1,78 @@
+sctools package
+===============
+
+
+Submodules
+~~~~~~~~~~
+
+sctools.bam module
+------------------
+
+.. automodule:: sctools.bam
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
+sctools.barcode module
+----------------------
+
+.. automodule:: sctools.barcode
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
+sctools.encodings module
+------------------------
+
+.. automodule:: sctools.encodings
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
+sctools.fastq module
+--------------------
+
+.. automodule:: sctools.fastq
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
+sctools.gtf module
+------------------
+
+.. automodule:: sctools.gtf
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
+sctools.platform module
+-----------------------
+
+.. automodule:: sctools.platform
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
+sctools.reader module
+---------------------
+
+.. automodule:: sctools.reader
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
+sctools.stats module
+--------------------
+
+.. automodule:: sctools.stats
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:

docs/source/sctools.test.rst

@@ -0,0 +1,69 @@
+sctools.test package
+====================
+
+Submodules
+~~~~~~~~~~
+
+sctools.test.test\_bam module
+-----------------------------
+
+.. automodule:: sctools.test.test_bam
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+sctools.test.test\_barcode module
+---------------------------------
+
+.. automodule:: sctools.test.test_barcode
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+sctools.test.test\_encodings module
+-----------------------------------
+
+.. automodule:: sctools.test.test_encodings
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+sctools.test.test\_entrypoints module
+-------------------------------------
+
+.. automodule:: sctools.test.test_entrypoints
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+sctools.test.test\_fastq module
+-------------------------------
+
+.. automodule:: sctools.test.test_fastq
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+sctools.test.test\_gtf module
+-----------------------------
+
+.. automodule:: sctools.test.test_gtf
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+sctools.test.test\_metrics module
+---------------------------------
+
+.. automodule:: sctools.test.test_metrics
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+sctools.test.test\_stats module
+-------------------------------
+
+.. automodule:: sctools.test.test_stats
+    :members:
+    :undoc-members:
+    :show-inheritance:

readthedocs.yml

@@ -0,0 +1,10 @@
+# .readthedocs.yml
+
+build:
+  image: latest
+
+python:
+  version: 3.6
+  use_system_site_packages: false  # Set to true will let the virtualenv use the pre-installed packages such as numpy, which is not what we want
+  setup_py_install: false
+  pip_install: true

requirements.txt

@@ -5,4 +5,6 @@ pandas>=0.22.0
 pytest>=3.4.2
 pytest-cov>=2.5.1
 scipy>=1.0.1
-crimson>=0.3.0
+crimson>=0.3.0
+setuptools>=40.4.3
+setuptools_scm>=3.1.0

setup.py

@@ -29,9 +29,10 @@
         'pytest',
         'pytest-cov',
         'sphinx',
-        'sphinxcontrib-napoleon',
+        'sphinxcontrib-websupport',
         'sphinx_rtd_theme',
-        'setuptools_scm',
+        'setuptools_scm>=3.1.0',
+        'setuptools>=40.4.3',
         'scipy>=1.0.0',
         'crimson>=0.3.0',