fix(docs): clean up sources and treat warnings as errors

Many deficiencies in the docs were being skipped over because
`sphinx-build` is lenient. Adding the `-W` flag treats issues
such as "missing reference" and "class not found" as errors.

Author: mboersma

client/deis.py

@@ -502,6 +502,7 @@ def apps_destroy(self, args):
         Options:
           -a --app=<app>
             the uniquely identifiable name for the application.
+
           --confirm=<app>
             skips the prompt for the application name. <app> is the uniquely identifiable
             name for the application.
@@ -914,19 +915,20 @@ def clusters_create(self, args):
         Arguments:
           <id>
             a uniquely identifiable name for the cluster, such as 'dev' or 'prod'.
+
           <domain>
             a domain under which app hostnames will live. This must be provided to support
             multiple applications hosted on the cluster.
-
-            Note: this requires wildcard DNS configuration on the domain. For example, a
+            NOTE: this requires wildcard DNS configuration on the domain. For example, a
             <domain> of `deisapp.com` requires that `*.deisapp.com` resolves to one of the
             cluster's router endpoints or the load balancer in front of the routers.
+
           --hosts=<hosts>
             a comma-separated list of the cluster members' private IP addresses.
+
           --auth=<auth>
             a local file path to an SSH private key. This is the key used to provision and
             connect to the cluster members. This key must not have a password.
-
             NOTE: for EC2 and Rackspace, this key is likely `~/.ssh/deis`.
 
         Options:
@@ -1108,6 +1110,7 @@ def config_list(self, args):
         Options:
           --oneline
             print output on one line.
+
           -a --app=<app>
             the uniquely identifiable name of the application.
         """
@@ -1899,6 +1902,7 @@ def perms_list(self, args):
           -a --app=<app>
             lists all users with permission to <app>. <app> is the uniquely identifiable name
             for the application.
+
           --admin
             lists all users with system administrator privileges.
         """
@@ -1924,6 +1928,7 @@ def perms_create(self, args):
           -a --app=<app>
             grants <username> permission to use <app>. <app> is the uniquely identifiable name
             for the application.
+
           --admin
             grants <username> system administrator privileges.
         """
@@ -1957,6 +1962,7 @@ def perms_delete(self, args):
           -a --app=<app>
             revokes <username> permission to use <app>. <app> is the uniquely identifiable name
             for the application.
+
           --admin
             revokes <username> system administrator privileges.
         """

controller/api/serializers.py

@@ -33,7 +33,7 @@ def from_native(self, data):
 
 
 class UserSerializer(serializers.ModelSerializer):
-    """Serialize a :class:`~api.models.User` model."""
+    """Serialize a User model."""
 
     class Meta:
         """Metadata options for a UserSerializer."""
@@ -52,7 +52,7 @@ def data(self):
 
 
 class AdminUserSerializer(serializers.ModelSerializer):
-    """Serialize admin status for a :class:`~api.models.User` model."""
+    """Serialize admin status for a User model."""
 
     class Meta:
         model = User

controller/api/urls.py

@@ -27,7 +27,7 @@
 
 .. http:get:: /api/apps/(string:id)/
 
-  Retrieve a :class:`~api.models.Application` by its `id`.
+  Retrieve a :class:`~api.models.App` by its `id`.
 
 .. http:delete:: /api/apps/(string:id)/
 
@@ -65,14 +65,6 @@
 
   Create a new :class:`~api.models.Build`.
 
-.. http:get:: /api/apps/(string:id)/limits/
-
-  Retrieve the latest :class:`~api.models.Limit`.
-
-.. http:post:: /api/apps/(string:id)/limits/
-
-  Create a new :class:`~api.models.Limit`.
-
 .. http:get:: /api/apps/(string:id)/releases/(int:version)/
 
   Retrieve a :class:`~api.models.Release` by its `version`.
@@ -137,11 +129,6 @@
   See also
   :meth:`AppViewSet.run() <api.views.AppViewSet.run>`
 
-.. http:post:: /api/apps/(string:id)/calculate/
-
-  See also
-  :meth:`AppViewSet.calculate() <api.views.AppViewSet.calculate>`
-
 
 Application Sharing
 ===================
@@ -200,11 +187,11 @@
 
 .. http:post:: /api/auth/register/
 
-  Create a new :class:`~django.contrib.auth.models.User`.
+  Create a new User.
 
 .. http:delete:: /api/auth/register/
 
-  Destroy the logged-in :class:`~django.contrib.auth.models.User`.
+  Destroy the logged-in User.
 
 .. http:post:: /api/auth/login
 
@@ -292,8 +279,6 @@
         views.AppViewSet.as_view({'post': 'logs'})),
     url(r'^apps/(?P<id>{})/run/?'.format(settings.APP_URL_REGEX),
         views.AppViewSet.as_view({'post': 'run'})),
-    url(r'^apps/(?P<id>{})/calculate/?'.format(settings.APP_URL_REGEX),
-        views.AppViewSet.as_view({'post': 'calculate'})),
     # apps sharing
     url(r'^apps/(?P<id>{})/perms/(?P<username>[-_\w]+)/?'.format(settings.APP_URL_REGEX),
         views.AppPermsViewSet.as_view({'delete': 'destroy'})),

controller/registry/private.py

@@ -19,9 +19,12 @@ def publish_release(source, config, target):
     Given a source image and dictionary of last-mile configuration,
     create a target Docker image on the registry.
 
-    For example publish_release('registry.local:5000/gabrtv/myapp:v22',
-                                {'ENVVAR': 'values'},
-                                'registry.local:5000/gabrtv/myapp:v23',)
+    For example::
+
+        publish_release('registry.local:5000/gabrtv/myapp:v22',
+                        {'ENVVAR': 'values'},
+                        'registry.local:5000/gabrtv/myapp:v23')
+
     results in a new Docker image at 'registry.local:5000/gabrtv/myapp:v23' which
     contains the new configuration as ENV entries.
     """

docs/Makefile

@@ -5,47 +5,31 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-PYTHON        = python
-ZIP           = zip
 BUILDDIR      = _build
 
 READTHEDOCS   = true
 export READTHEDOCS
 
+# # User-friendly check for sphinx-build
+# ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+# $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+# endif
+
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: test check-sphinx help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
-
-test: clean
-	@if [ ! -d venv ]; then virtualenv venv; fi
-	venv/bin/pip install -q -r docs_requirements.txt
-	venv/bin/$(SPHINXBUILD) -a -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	test -f $(BUILDDIR)/dirhtml/index.html
-
-check-sphinx:
-	# User-friendly check for sphinx-build
-	ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-	$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-	endif
-
-dirhtml: check-sphinx
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-auto: dirhtml
-	sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+.PHONY: help clean test html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  server     to make dirhtml as above, then serve it at http://0.0.0.0:8000/"
+	@echo "  server     to make HTML as above and serve it at http://localhost:8000/"
+	@echo "  test       to validate the dirhtml output"
 	@echo "  singlehtml to make a single large HTML file"
 	@echo "  pickle     to make pickle files"
 	@echo "  json       to make JSON files"
@@ -68,38 +52,51 @@ help:
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
-	rm -rf docs.zip $(BUILDDIR)/*
-
-zipfile: dirhtml
-	cd $(BUILDDIR)/dirhtml; $(ZIP) -r -D -o ../../docs.zip .
+	rm -rf $(BUILDDIR)/*
 
-html: check-sphinx
+html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-singlehtml: check-sphinx
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+server: dirhtml
+	@cd $(BUILDDIR)/dirhtml; python -m SimpleHTTPServer 8000
+
+test: clean
+	@if [ ! -d venv ]; then virtualenv venv; fi
+	venv/bin/pip install -q -r docs_requirements.txt
+	venv/bin/$(SPHINXBUILD) -b dirhtml -N -W $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	grep -q \<h1\>Welcome _build/dirhtml/index.html || exit 1
+	@echo
+	@echo "Test finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
-pickle: check-sphinx
+pickle:
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
-json: check-sphinx
+json:
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp: check-sphinx
+htmlhelp:
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
-qthelp: check-sphinx
+qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -108,7 +105,7 @@ qthelp: check-sphinx
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/deis.qhc"
 
-devhelp: check-sphinx
+devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -117,83 +114,80 @@ devhelp: check-sphinx
 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/deis"
 	@echo "# devhelp"
 
-epub: check-sphinx
+epub:
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
-latex: check-sphinx
+latex:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
-latexpdf: check-sphinx
+latexpdf:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
-latexpdfja: check-sphinx
+latexpdfja:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through platex and dvipdfmx..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
-text: check-sphinx
+text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
-man: check-sphinx
+man:
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
-texinfo: check-sphinx
+texinfo:
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
 
-info: check-sphinx
+info:
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
 
-gettext: check-sphinx
+gettext:
 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
-changes: check-sphinx
+changes:
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
-linkcheck: check-sphinx
+linkcheck:
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
-doctest: check-sphinx
+doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
-xml: check-sphinx
+xml:
 	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
 	@echo
 	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
 
-pseudoxml: check-sphinx
+pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
-
-server: dirhtml
-	@cd $(BUILDDIR)/dirhtml; $(PYTHON) -m SimpleHTTPServer 8000

docs/contributing/releases.rst

@@ -7,15 +7,7 @@ Release Checklist
 =================
 
 These instructions are to assist the Deis maintainers with creating a new Deis
-product release.
-
-.. image:: http://upload.wikimedia.org/wikipedia/commons/3/37/Grace_Hopper_and_UNIVAC.jpg
-  :width: 220
-  :height: 193
-  :align: right
-  :alt: Grace Hopper and UNIVAC, from the Wikimedia Commons
-
-Please keep this document up-to-date with any changes in this process.
+product release. Please keep this document up-to-date with any changes in this process.
 
 deis Repo
 ---------