docs: Fix sphinx documentation failures (#219)

Our documentation file had a configuration issue, which emits a warning
when building with sphinx. This caused the build process on
readthedocs.org to fail because they treat warnings as errors.

We didn't catch this because:

1. Warnings are treated like warnings when generating documentation
   locally.
2. We don't try to generate the documentation as part of our CI process.

This commit should resolve both the underlying issue and the
deficiencies that prevented us from catching this initially.

Author: keelerm84

.circleci/config.yml

@@ -9,6 +9,7 @@ workflows:
       - test-linux:
           name: Python 3.7
           docker-image: cimg/python:3.7
+          test-build-docs: true
       - test-linux:
           name: Python 3.8
           docker-image: cimg/python:3.8
@@ -33,6 +34,9 @@ jobs:
       test-packaging:
         type: boolean
         default: true
+      test-build-docs:
+        type: boolean
+        default: false
       test-with-codeclimate:
         type: boolean
         default: false
@@ -95,6 +99,13 @@ jobs:
                 command: |
                   export PATH="/home/circleci/.local/bin:$PATH"
                   make lint
+      - when:
+          condition: <<parameters.test-build-docs>>
+          steps:
+            - run:
+                name: verify docs can be built successfully
+                command: |
+                  make docs
 
       - unless:
           condition: <<parameters.skip-sse-contract-tests>>

docs/Makefile

@@ -3,7 +3,7 @@
 
 .PHONY: help install html
 
-SPHINXOPTS    =
+SPHINXOPTS    = -W --keep-going
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = launchdarkly-server-sdk
 SOURCEDIR     = .

docs/api-main.rst

@@ -6,14 +6,12 @@ ldclient module
 
 .. automodule:: ldclient
     :members: Context,ContextBuilder,ContextMultiBuilder,get,set_config
-    :special-members: __init__
 
 ldclient.client module
 ----------------------
 
 .. automodule:: ldclient.client
     :members: LDClient
-    :special-members: __init__
 
 ldclient.config module
 ----------------------

docs/conf.py

@@ -68,7 +68,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.