(WIP) initial attempt at menpo3d docs

docs/.gitignore

@@ -0,0 +1 @@
+_build/*

docs/Makefile

@@ -0,0 +1,65 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+N_CORES       = $(shell getconf _NPROCESSORS_ONLN)
+SPHINXOPTS    = -j $(N_CORES)
+SPHINXBUILD   = sphinx-build
+PAPER         =
+SRC_DIR       = source
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRC_DIR)
+
+.PHONY: help clean html changes linkcheck
+
+default: html
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html        standalone HTML files"
+	@echo "  changes     an overview over all changed/added/deprecated items"
+	@echo "  linkcheck   check all external links for integrity (takes a long time)"
+	@echo
+	@echo "Compound utility targets:"
+	@echo "pdf          latex and then runs the PDF generation"
+	@echo "all          html and pdf"
+	@echo "dist         all, and then puts the results in dist/"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+pdf: latex
+	cd $(BUILDDIR)/latex && make all-pdf
+
+all: html pdf
+
+html:
+	mkdir -p $(BUILDDIR)/html $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+latex:
+	mkdir -p $(BUILDDIR)/latex $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	mkdir -p $(BUILDDIR)/changes $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	mkdir -p $(BUILDDIR)/linkcheck $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.rst."

docs/generate_rst.py

@@ -0,0 +1,87 @@
+from inspect import isclass, isfunction, ismodule
+from functools import partial
+
+is_func_or_partial = lambda f: isfunction(f) or isinstance(f, partial)
+
+
+def write_docs_for_module(module, path, modules_to_skip=None,
+                          generate_index=False):
+    if modules_to_skip is None:
+        modules_to_skip = {}
+    module_name = module.__name__
+    doc_dir = path / module_name
+    if not doc_dir.is_dir():
+        doc_dir.mkdir()
+    for k, v in module.__dict__.items():
+        if ismodule(v):
+            print('Writing module {}'.format(module_name))
+            file_to_doc = docs_for_module(k, v, module_name,
+                                          generate_index=generate_index)
+            if len(file_to_doc) == 0 or k in modules_to_skip:
+                continue
+            mod_dir = doc_dir / k
+            if not mod_dir.is_dir():
+                mod_dir.mkdir()
+            for f_name in file_to_doc:
+                doc_file = mod_dir / (f_name + '.rst')
+                with open(str(doc_file), 'wb') as f:
+                    f.write(file_to_doc[f_name])
+
+
+def docs_for_module(module_name, module, package_name, generate_index=False):
+    file_to_doc = {}
+    for k, v in module.__dict__.items():
+        if isclass(v):
+            file_to_doc[k] = generate_class_rst(module_name, k,
+                                                module.__name__, package_name)
+        elif is_func_or_partial(v):
+            file_to_doc[k] = generate_function_rst(module_name, k,
+                                                   module.__name__,
+                                                   package_name)
+    # only make an index if there is something to index
+    if generate_index and len(file_to_doc) > 0:
+        file_to_doc['index'] = generate_module_index(module_name, module)
+    return file_to_doc
+
+
+def generate_module_index(module_name, module):
+    breadcrumb = '.. _api-{}-index:\n\n'.format(module_name)
+    title = ":mod:`{}`".format(module.__name__)
+    title = "{}\n{}\n".format(title, '=' * len(title))
+    toctree = "\n.. toctree::\n  :maxdepth: 1\n\n  "
+    items = [i for i, v in module.__dict__.items() if isclass(v) or
+             is_func_or_partial(v)]
+    return breadcrumb + title + toctree + "\n  ".join(items)
+
+
+def generate_class_rst(module_name, class_name, module, package_name):
+    breadcrumb = '.. _{}-{}-{}:\n\n'.format(package_name, module_name,
+                                            class_name)
+    current_module = '.. currentmodule:: {}\n\n'.format(module)
+    title = "{}\n{}\n".format(class_name, '=' * len(class_name))
+    body = (".. autoclass:: {}\n  :members:\n  :inherited-members:"
+            "\n  :show-inheritance:\n".format(class_name))
+    return breadcrumb + current_module + title + body
+
+
+def generate_function_rst(module_name, function_name, module, package_name):
+    breadcrumb = '.. _{}-{}-{}:\n\n'.format(package_name, module_name,
+                                            function_name)
+    current_module = '.. currentmodule:: {}\n\n'.format(module)
+    title = "{}\n{}\n".format(function_name, '=' * len(function_name))
+    body = ".. autofunction:: {}\n".format(function_name)
+    return breadcrumb + current_module + title + body
+
+
+
+if __name__ == '__main__':
+    from pathlib import Path
+    import menpo3d
+
+    path = Path(__file__).parent / 'source' / 'api'
+    print('Writing to {}'.format(path))
+
+    # Flip generate_index to True to make index.rst files too!
+    write_docs_for_module(menpo3d, path, generate_index=False,
+                          modules_to_skip={'_version'})
+

docs/rtd_environment.yml

@@ -0,0 +1,12 @@
+name: menpofit_rtd
+channels:
+  - menpo
+dependencies:
+  - python
+  - setuptools
+
+  - menpo >=0.7,<0.8
+  - pip:
+      - sphinx
+      - sphinx_rtd_theme
+      - sphinxmapxrefrole>0.2

docs/source/_static/rtd_hack.css

@@ -0,0 +1,31 @@
+/* Code References (using the class or map commands) */
+a>code.xref.py.py-class.docutils.literal,a>code.xref.py.py-function.docutils.literal {
+    color: #2980B9;
+    font-weight: bold;
+    padding: 0;
+    font-size: 90%;
+}
+a:hover>code.xref.py.py-class.docutils.literal,a:hover>code.xref.py.py-function.docutils.literal {
+    color: purple;
+}
+/* Class names */
+code.descclassname, code.descname {
+    background-color: transparent;
+    font-size: 100% !important;
+    border: none;
+    padding: 0;
+    color: #000000;
+}
+/* Inline Code */
+code.docutils.literal {
+    color: #000000;
+    font-weight: bold;
+}
+/* Inline Code Links e.g. for module links*/
+a>code.docutils.literal {
+    color: gray;
+    font-weight: bold;
+    border: none;
+    background: transparent;
+    font-size: 80%;
+}