Update doc setup (#673)

* Expose doc commands in root makefile and add autobuild

* Fix some errors

* Alias some commands and add PHONY

Makefile

@@ -1,11 +1,29 @@
+.PHONY: dev-setup ## Install development dependencies
 dev-setup:
 	pip install -e ".[dev]"
 
+.PHONY: install-dev
+install-dev: dev-setup  # Alias install-dev -> dev-setup
+
+.PHONY: tests
 tests:
 	py.test graphene_django --cov=graphene_django -vv
 
+.PHONY: test
+test: tests  # Alias test -> tests
+
+.PHONY: format
 format:
 	black --exclude "/migrations/" graphene_django examples
 
+.PHONY: lint
 lint:
 	flake8 graphene_django examples
+
+.PHONY: docs ## Generate docs
+docs: dev-setup
+	cd docs && make install && make html
+
+.PHONY: docs-live ## Generate docs with live reloading
+docs-live: dev-setup
+	cd docs && make install && make livehtml

docs/Makefile

@@ -48,12 +48,20 @@ help:
 clean:
 	rm -rf $(BUILDDIR)/*
 
+.PHONY: install ## to install all documentation related requirements
+install:
+	pip install -r requirements.txt
+
 .PHONY: html
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+.PHONY: livehtml ## to build and serve live-reloading documentation
+livehtml:
+	sphinx-autobuild -b html --watch ../graphene_django $(ALLSPHINXOPTS) $(BUILDDIR)/html
+
 .PHONY: dirhtml
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml

docs/authorization.rst

@@ -154,6 +154,7 @@ Adding Login Required
 To restrict users from accessing the GraphQL API page the standard Django LoginRequiredMixin_ can be used to create your own standard Django Class Based View, which includes the ``LoginRequiredMixin`` and subclasses the ``GraphQLView``.:
 
 .. code:: python
+
     # views.py
 
     from django.contrib.auth.mixins import LoginRequiredMixin

docs/requirements.txt

@@ -1,3 +1,4 @@
-sphinx
+Sphinx==1.5.3
+sphinx-autobuild==0.7.1
 # Docs template
 http://graphene-python.org/sphinx_graphene_theme.zip

docs/settings.rst

@@ -30,7 +30,7 @@ Default: ``None``
 
 
 ``SCHEMA_OUTPUT``
-----------
+-----------------
 
 The name of the file where the GraphQL schema output will go.
 
@@ -44,7 +44,7 @@ Default: ``schema.json``
 
 
 ``SCHEMA_INDENT``
-----------
+-----------------
 
 The indentation level of the schema output.
 
@@ -58,7 +58,7 @@ Default: ``2``
 
 
 ``MIDDLEWARE``
-----------
+--------------
 
 A tuple of middleware that will be executed for each GraphQL query.
 
@@ -76,7 +76,7 @@ Default: ``()``
 
 
 ``RELAY_CONNECTION_ENFORCE_FIRST_OR_LAST``
-----------
+------------------------------------------
 
 Enforces relay queries to have the ``first`` or ``last`` argument.
 
@@ -90,7 +90,7 @@ Default: ``False``
 
 
 ``RELAY_CONNECTION_MAX_LIMIT``
-----------
+------------------------------
 
 The maximum size of objects that can be requested through a relay connection.