build(sphinx): Port back to sphinx

Author: tony

docs/.prettierignore

@@ -0,0 +1 @@
+api.md

docs/Makefile

@@ -1,5 +1,6 @@
 # Makefile for Sphinx documentation
 #
+SHELL := /bin/bash
 PYVERSION=$(shell python -c "import sys;v=sys.version_info[0];sys.stdout.write(str(v))")
 HTTP_PORT     = 8068
 
@@ -166,13 +167,16 @@ watch:
 serve:
 	@echo '=============================================================='
 	@echo
-	@echo 'docs server running at http://0.0.0.0:${HTTP_PORT}/_build/html'
+	@echo 'docs server running at http://0.0.0.0:${HTTP_PORT}/'
 	@echo
 	@echo '=============================================================='
 	@if test ${PYVERSION} -eq 2; then $(MAKE) serve_py2; else make serve_py3; fi
 
 serve_py2:
-	python -m SimpleHTTPServer ${HTTP_PORT}
+	pushd _build/html; python2 -m SimpleHTTPServer ${HTTP_PORT}; popd
 
 serve_py3:
-	python -m http.server ${HTTP_PORT}
+	python -m http.server ${HTTP_PORT} --directory _build/html
+
+dev:
+	$(MAKE) -j watch serve

docs/api.rst renamed to docs/api.md

@@ -1,31 +1,29 @@
 .. _api:
 
-=============
-API Reference
-=============
+# API Reference
 
-Creating a repo object
-----------------------
+## Creating a repo object
 
 Helper methods are available in ``libvcs.shortcuts`` which
 can return a repo object from a single entry-point.
 
+```eval_rst
 .. autofunction:: libvcs.shortcuts.create_repo
 
 .. autofunction:: libvcs.shortcuts.create_repo_from_pip_url
+```
 
-Instantiating a repo by hand
-----------------------------
+## Instantiating a repo by hand
 
 Tools like :func:`libvcs.shortcuts.create_repo` and
 :func:`libvcs.shortcuts.create_repo_from_pip_url` are just wrappers
 around instantiated these classes.
 
 See examples below of git, mercurial, and subversion.
 
-Git
----
+### Git
 
+```eval_rst
 .. autoclass:: libvcs.git.GitRepo
    :members:
    :show-inheritance:
@@ -35,36 +33,41 @@ Git
    :show-inheritance:
 
 .. autofunction:: libvcs.git.extract_status
+```
 
-Mercurial
----------
+### Mercurial
 
 aka ``hg(1)``
 
+```eval_rst
 .. autoclass:: libvcs.hg.MercurialRepo
    :members:
    :show-inheritance:
+```
 
-Subversion
-----------
+### Subversion
 
 aka ``svn(1)``
 
+```eval_rst
 .. autoclass:: libvcs.svn.SubversionRepo
    :members:
    :show-inheritance:
+```
 
-Adding your own VCS
--------------------
+### Adding your own VCS
 
 Extending libvcs can be done through subclassing ``BaseRepo``.
 
+```eval_rst
 .. autoclass:: libvcs.base.BaseRepo
     :members:
     :show-inheritance:
+```
 
-Utility stuff
--------------
+### Utility stuff
 
+```eval_rst
 .. automodule:: libvcs.util
    :members:
+```

docs/conf.py

@@ -12,13 +12,17 @@
 with open("../libvcs/__about__.py") as fp:
     exec(fp.read(), about)
 
+import recommonmark
+from recommonmark.transform import AutoStructify
+
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.napoleon',
     'alagitpull',
     'sphinx_issues',
+    'recommonmark',
 ]
 
 releases_unstable_prehistory = True
@@ -30,10 +34,27 @@
 
 templates_path = ['_templates']
 
-source_suffix = '.rst'
+source_suffix = {'.rst': 'restructuredtext', '.md': 'markdown'}
 
 master_doc = 'index'
 
+# app setup hook
+def setup(app):
+    app.add_config_value(
+        'recommonmark_config',
+        {
+            #'url_resolver': lambda url: github_doc_root + url,
+            'enable_auto_toc_tree': True,
+            'auto_toc_tree_section': 'Contents',
+            'enable_auto_doc_ref': True,
+            'auto_code_block': True,
+            'enable_eval_rst': True,
+        },
+        True,
+    )
+    app.add_transform(AutoStructify)
+
+
 project = about['__title__']
 copyright = about['__copyright__']