Merge pull request #3426 from jtschladen/fix-docs

Enable fail on warning for docs

.readthedocs.yml

@@ -8,6 +8,7 @@ version: 2
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
    configuration: docs/conf.py
+   fail_on_warning: true
 
 # Build docs in all formats (html, pdf, epub)
 formats: all

CHANGELOG.rst

@@ -247,7 +247,7 @@ these keys should be fairly trivial, additionally pull requests have been submit
     should be easier to determine what authorities are available and when an authority has actually been selected.
 * Closed `#254 <https://github.com/Netflix/lemur/issues/254>`_ - Forces certificate names to be generally unique. If a certificate name
     (generated or otherwise) is found to be a duplicate we increment by appending a counter.
-* Closed `#254 <https://github.com/Netflix/lemur/issues/275>`_ - Switched to using Fernet generated passphrases for exported items.
+* Closed `#275 <https://github.com/Netflix/lemur/issues/275>`_ - Switched to using Fernet generated passphrases for exported items.
     These are more sounds that pseudo random passphrases generated before and have the nice property of being in base64.
 * Closed `#278 <https://github.com/Netflix/lemur/issues/278>`_ - Added ability to specify a custom name to certificate creation, previously
     this was only available in the certificate import wizard.

docs/conf.py

@@ -32,6 +32,9 @@ if on_rtd:
     MOCK_MODULES = ["ldap"]
     sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
 
+autodoc_mock_imports = ["python-ldap", "acme", "certsrv", "dnspython3", "dyn", "factory-boy", "flask_replicated",
+                        "josepy", "logmatic", "pem"]
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -146,7 +149,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/developer/index.rst

@@ -43,6 +43,13 @@ Building Documentation
 Inside the ``docs`` directory, you can run ``make`` to build the documentation.
 See ``make help`` for available options and the `Sphinx Documentation <http://sphinx-doc.org/contents.html>`_ for more information.
 
+Adding New Modules to Documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a new module is added, it will need to be added to the documentation.
+Ideally, we might rely on `sphinx-apidoc <https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html>`_ to autogenerate our documentation.
+Unfortunately, this causes some build problems.
+Instead, you'll need to add new modules by hand.
 
 Developing Against HEAD
 -----------------------

docs/developer/internals/lemur.defaults.rst

@@ -0,0 +1,29 @@
+defaults Package
+================
+
+:mod:`defaults` Module
+----------------------------------------
+
+.. automodule:: lemur.defaults
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`schemas` Module	
+-----------------------------	
+
+.. automodule:: lemur.defaults.schemas	
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`views` Module	
+---------------------------	
+
+.. automodule:: lemur.defaults.views	
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.deployment.rst

@@ -0,0 +1,20 @@
+deployment Package
+===================
+
+:mod:`deployment` Module
+----------------------------------------
+
+.. automodule:: lemur.deployment
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`service` Module	
+------------------------------	
+
+.. automodule:: lemur.deployment.service
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.endpoints.rst

@@ -0,0 +1,56 @@
+endpoints Package
+===================
+
+:mod:`endpoints` Module
+----------------------------------------
+
+.. automodule:: lemur.endpoints
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`cli` Module	
+--------------------------	
+
+.. automodule:: lemur.endpoints.cli
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`models` Module	
+-----------------------------	
+
+.. automodule:: lemur.endpoints.models
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`schemas` Module	
+------------------------------	
+
+.. automodule:: lemur.endpoints.schemas
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`service` Module	
+------------------------------	
+
+.. automodule:: lemur.endpoints.service	
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`views` Module	
+----------------------------	
+
+.. automodule:: lemur.endpoints.views	
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.logs.rst

@@ -0,0 +1,47 @@
+logs Package
+===================
+
+:mod:`logs` Module
+--------------------
+
+.. automodule:: lemur.logs
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`models` Module
+------------------------------	
+
+.. automodule:: lemur.logs.models
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`schemas` Module
+------------------------------
+
+.. automodule:: lemur.logs.schemas
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`service` Module
+------------------------------
+
+.. automodule:: lemur.logs.service
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`views` Module
+------------------------------
+
+.. automodule:: lemur.logs.views
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.plugins.lemur_acme.rst

@@ -0,0 +1,83 @@
+lemur_acme package	
+=================================	
+
+:mod:`lemur_acme` Module
+----------------------------------------
+
+.. automodule:: lemur.plugins.lemur_acme
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`acme_handlers` Module
+-----------------------------------------------	
+
+.. automodule:: lemur.plugins.lemur_acme.acme_handlers	
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`challenge_types` Module
+-------------------------------------------------	
+
+.. automodule:: lemur.plugins.lemur_acme.challenge_types	
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`cloudflare` Module
+-------------------------------------------	
+
+.. automodule:: lemur.plugins.lemur_acme.cloudflare	
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`dyn` Module
+------------------------------------	
+
+.. automodule:: lemur.plugins.lemur_acme.dyn	
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`plugin` Module
+---------------------------------------	
+
+.. automodule:: lemur.plugins.lemur_acme.plugin	
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`powerdns` Module
+-----------------------------------------	
+
+.. automodule:: lemur.plugins.lemur_acme.powerdns	
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`route53` Module
+----------------------------------------	
+
+.. automodule:: lemur.plugins.lemur_acme.route53	
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`ultradns` Module
+-----------------------------------------	
+
+.. automodule:: lemur.plugins.lemur_acme.ultradns	
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.plugins.lemur_atlas.rst

@@ -0,0 +1,20 @@
+lemur_atlas package
+==================================
+
+:mod:`lemur_atlas` Module
+----------------------------------------
+
+.. automodule:: lemur.plugins.lemur_atlas
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`plugin` Module
+--------------------
+
+.. automodule:: lemur.plugins.lemur_atlas.plugin
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.plugins.lemur_cryptography.rst

@@ -0,0 +1,20 @@
+lemur_cryptography package
+==================================
+
+:mod:`lemur_cryptography` Module
+----------------------------------------
+
+.. automodule:: lemur.plugins.lemur_cryptography
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`plugin` Module
+--------------------
+
+.. automodule:: lemur.plugins.lemur_cryptography.plugin
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.plugins.lemur_digicert.rst

@@ -0,0 +1,20 @@
+lemur_digicert package
+==================================
+
+:mod:`lemur_digicert` Module
+----------------------------------------
+
+.. automodule:: lemur.plugins.lemur_digicert
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`plugin` Module
+--------------------
+
+.. automodule:: lemur.plugins.lemur_digicert.plugin
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.plugins.lemur_jks.rst

@@ -0,0 +1,20 @@
+lemur_jks package
+==================================
+
+:mod:`lemur_jks` Module
+----------------------------------------
+
+.. automodule:: lemur.plugins.lemur_jks
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`plugin` Module
+--------------------
+
+.. automodule:: lemur.plugins.lemur_jks.plugin
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.plugins.lemur_kubernetes.rst

@@ -0,0 +1,20 @@
+lemur_kubernetes package
+==================================
+
+:mod:`lemur_kubernetes` Module
+----------------------------------------
+
+.. automodule:: lemur.plugins.lemur_kubernetes
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`plugin` Module
+--------------------
+
+.. automodule:: lemur.plugins.lemur_kubernetes.plugin
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.plugins.lemur_openssl.rst

@@ -0,0 +1,20 @@
+lemur_openssl package
+==================================
+
+:mod:`lemur_openssl` Module
+----------------------------------------
+
+.. automodule:: lemur.plugins.lemur_openssl
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`plugin` Module
+--------------------
+
+.. automodule:: lemur.plugins.lemur_openssl.plugin
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.plugins.lemur_slack.rst

@@ -0,0 +1,20 @@
+lemur_slack package
+==================================
+
+:mod:`lemur_slack` Module
+----------------------------------------
+
+.. automodule:: lemur.plugins.lemur_slack
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`plugin` Module
+--------------------
+
+.. automodule:: lemur.plugins.lemur_slack.plugin
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.reporting.rst

@@ -0,0 +1,38 @@
+reporting Package
+===================
+
+:mod:`reporting` Module
+----------------------------------------
+
+.. automodule:: lemur.reporting
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`cli` Module
+------------------------------	
+
+.. automodule:: lemur.reporting.cli
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`service` Module
+------------------------------
+
+.. automodule:: lemur.reporting.service
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`views` Module
+------------------------------
+
+.. automodule:: lemur.reporting.views
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.rst

@@ -28,15 +28,6 @@ lemur Package
     :undoc-members:
     :show-inheritance:
 
-:mod:`decorators` Module
-------------------------
-
-.. automodule:: lemur.decorators
-    :noindex:
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 :mod:`exceptions` Module
 ------------------------
 
@@ -108,7 +99,7 @@ Subpackages
     lemur.plugins.lemur_atlas
     lemur.plugins.lemur_cryptography
     lemur.plugins.lemur_digicert
-    lemur.plugins.lemur_java
+    lemur.plugins.lemur_jks
     lemur.plugins.lemur_kubernetes
     lemur.plugins.lemur_openssl
     lemur.plugins.lemur_slack

docs/developer/internals/lemur.sources.rst

@@ -0,0 +1,56 @@
+sources Package
+===================
+
+:mod:`sources` Module
+----------------------
+
+.. automodule:: lemur.sources
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`cli` Module
+------------------------------	
+
+.. automodule:: lemur.sources.cli
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`models` Module
+------------------------------
+
+.. automodule:: lemur.sources.models
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`schemas` Module
+------------------------------
+
+.. automodule:: lemur.sources.schemas
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`service` Module
+------------------------------
+
+.. automodule:: lemur.sources.service
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`views` Module
+------------------------------
+
+.. automodule:: lemur.sources.views
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/developer/internals/lemur.tests.rst

@@ -0,0 +1,11 @@
+tests Package
+=============
+
+:mod:`tests` Module
+--------------------
+
+.. automodule:: lemur.tests
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/license/index.rst

@@ -18,3 +18,4 @@ Lemur License
 -------------
 
 .. include:: ../../LICENSE
+    :literal:

lemur/certificates/views.py

@@ -60,8 +60,7 @@ class CertificatesListValid(AuthenticatedResource):
 
            .. sourcecode:: http
 
-              GET /certificates/valid?filter=cn;*.test.example.net&owner=joe@example.com&page=1&count=20
-              HTTP/1.1
+              GET /certificates/valid?filter=cn;*.test.example.net&owner=joe@example.com&page=1&count=20 HTTP/1.1
               Host: example.com
               Accept: application/json, text/javascript
 

lemur/dns_providers/service.py

@@ -36,7 +36,7 @@ def get_friendly(dns_provider_id):
     Retrieves a dns provider by its lemur assigned ID.
 
     :param dns_provider_id: Lemur assigned ID
-    :rtype : DnsProvider
+    :rtype: DnsProvider
     :return:
     """
     dns_provider = get(dns_provider_id)

lemur/dns_providers/views.py

@@ -86,9 +86,18 @@ class DnsProvidersList(AuthenticatedResource):
     @admin_permission.require(http_exception=403)
     def post(self, data=None):
         """
+        .. http:post:: /dns_providers
+
            Creates a DNS Provider
 
            **Example request**:
+
+           .. sourcecode:: http
+
+              POST /dns_providers HTTP/1.1
+              Host: example.com
+              Accept: application/json, text/javascript
+
                 {
                   "providerType": {
                     "name": "route53",
@@ -112,7 +121,14 @@ class DnsProvidersList(AuthenticatedResource):
                   "description": "provider_description"
                 }
 
-        **Example request 2**
+        **Example request 2**:
+
+           .. sourcecode:: http
+
+              HTTP/1.1 200 OK
+              Vary: Accept
+              Content-Type: text/javascript
+
                 {
                   "providerType": {
                     "name": "cloudflare",
@@ -142,6 +158,7 @@ class DnsProvidersList(AuthenticatedResource):
                   "name": "provider_name",
                   "description": "provider_description"
                 }
+
         :return:
         """
         return service.create(data)

lemur/domains/views.py

@@ -96,7 +96,7 @@ class DomainsList(AuthenticatedResource):
 
            .. sourcecode:: http
 
-              GET /domains HTTP/1.1
+              POST /domains HTTP/1.1
               Host: example.com
               Accept: application/json, text/javascript
 

lemur/pending_certificates/service.py

@@ -93,11 +93,10 @@ def get_pending_certs(pending_ids):
 def create_certificate(pending_certificate, certificate, user):
     """
     Create and store a certificate with pending certificate's info
-    Args:
-        pending_certificate: PendingCertificate which will populate the certificate
-        certificate: dict from Authority, which contains the body, chain and external id
-        user: User that called this function, used as 'creator' of the certificate if it does
-              not have an owner
+
+    :arg pending_certificate: PendingCertificate which will populate the certificate
+    :arg certificate: dict from Authority, which contains the body, chain and external id
+    :arg user: User that called this function, used as 'creator' of the certificate if it does not have an owner
     """
     certificate["owner"] = pending_certificate.owner
     data, errors = CertificateUploadInputSchema().load(certificate)
@@ -158,9 +157,9 @@ def cancel(pending_certificate, **kwargs):
     """
     Cancel a pending certificate.  A check should be done prior to this function to decide to
     revoke the certificate or just abort cancelling.
-    Args:
-        pending_certificate: PendingCertificate to be cancelled
-    Returns: the pending certificate if successful, raises Exception if there was an issue
+
+    :arg pending_certificate: PendingCertificate to be cancelled
+    :return: the pending certificate if successful, raises Exception if there was an issue
     """
     plugin = plugins.get(pending_certificate.authority.plugin_name)
     plugin.cancel_ordered_certificate(pending_certificate, **kwargs)

lemur/pending_certificates/views.py

@@ -221,7 +221,7 @@ class PendingCertificates(AuthenticatedResource):
 
            .. sourcecode:: http
 
-              PUT /pending certificates/1 HTTP/1.1
+              PUT /pending_certificates/1 HTTP/1.1
               Host: example.com
               Accept: application/json, text/javascript
               Content-Type: application/json;charset=UTF-8
@@ -338,7 +338,7 @@ class PendingCertificates(AuthenticatedResource):
 
            .. sourcecode:: http
 
-              DELETE /pending certificates/1 HTTP/1.1
+              DELETE /pending_certificates/1 HTTP/1.1
               Host: example.com
               Accept: application/json, text/javascript
 

lemur/plugins/bases/destination.py

@@ -31,6 +31,11 @@ class ExportDestinationPlugin(DestinationPlugin):
 
     @property
     def options(self):
+        """
+        Gets/sets options for the plugin.
+
+        :return:
+        """
         return self.default_options + self.additional_options
 
     def export(self, body, private_key, cert_chain, options):

lemur/plugins/bases/notification.py

@@ -57,6 +57,11 @@ class ExpirationNotificationPlugin(NotificationPlugin):
 
     @property
     def options(self):
+        """
+        Gets/sets options for the plugin.
+
+        :return:
+        """
         return self.default_options + self.additional_options
 
     def send(self, notification_type, message, excluded_targets, options, **kwargs):

lemur/plugins/bases/source.py

@@ -33,4 +33,9 @@ class SourcePlugin(Plugin):
 
     @property
     def options(self):
+        """
+        Gets/sets options for the plugin.
+
+        :return:
+        """
         return self.default_options + self.additional_options

lemur/plugins/lemur_acme/acme_handlers.py

@@ -71,7 +71,7 @@ class AcmeHandler(object):
             return False
 
     def strip_wildcard(self, host):
-        """Removes the leading *. and returns Host and whether it was removed or not (True/False)"""
+        """Removes the leading wildcard and returns Host and whether it was removed or not (True/False)"""
         prefix = "*."
         if host.startswith(prefix):
             return host[len(prefix):], True

lemur/roles/views.py

@@ -114,7 +114,7 @@ class RolesList(AuthenticatedResource):
                  "username": null,
                  "password": null,
                  "users": [
-                    {'id': 1}
+                    {"id": 1}
                  ]
               }
 
@@ -177,7 +177,7 @@ class RoleViewCredentials(AuthenticatedResource):
               Content-Type: text/javascript
 
               {
-                  "username: "ausername",
+                  "username": "ausername",
                   "password": "apassword"
               }
 

lemur/sources/service.py

@@ -255,7 +255,7 @@ def create(label, plugin_name, options, description=None):
     :param plugin_name:
     :param options:
     :param description:
-    :rtype : Source
+    :rtype: Source
     :return: New source
     """
     source = Source(
@@ -273,7 +273,7 @@ def update(source_id, label, plugin_name, options, description):
     :param options:
     :param plugin_name:
     :param description:
-    :rtype : Source
+    :rtype: Source
     :return:
     """
     source = get(source_id)
@@ -300,7 +300,7 @@ def get(source_id):
     Retrieves an source by its lemur assigned ID.
 
     :param source_id: Lemur assigned ID
-    :rtype : Source
+    :rtype: Source
     :return:
     """
     return database.get(Source, source_id)

lemur/static/app/angular/notifications/notification/notification.js

@@ -49,7 +49,6 @@ angular.module('lemur')
         });
       });
       NotificationService.getCertificates(notification);
-      $scope.page = 1;
     });
 
     $scope.save = function (notification) {
@@ -77,10 +76,5 @@ angular.module('lemur')
       $uibModalInstance.dismiss('cancel');
     };
 
-    $scope.loadMoreCertificates = function () {
-      $scope.page++;
-      NotificationService.loadMoreCertificates($scope.notification, $scope.page);
-    };
-
     $scope.certificateService = CertificateService;
   });

lemur/static/app/angular/notifications/services.js

@@ -42,7 +42,7 @@ angular.module('lemur')
     NotificationService.loadMoreCertificates = function (notification, page) {
       notification.getList('certificates', {page: page, showExpired: 0}).then(function (certificates) {
         _.each(certificates, function (certificate) {
-          notification.certificates.push(certificate);
+          notification.roles.push(certificate);
         });
       });
     };

lemur/users/views.py

@@ -101,7 +101,7 @@ class UsersList(AuthenticatedResource):
 
            Creates a new user
 
-           **Example request**:
+           **Example request with ID**:
 
            .. sourcecode:: http
 
@@ -115,7 +115,25 @@ class UsersList(AuthenticatedResource):
                  "email": "user3@example.com",
                  "active": true,
                  "roles": [
-                    {'id': 1} - or - {'name': 'myRole'}
+                    {"id": 1}
+                 ]
+              }
+
+           **Example request with name**:
+
+           .. sourcecode:: http
+
+              POST /users HTTP/1.1
+              Host: example.com
+              Accept: application/json, text/javascript
+              Content-Type: application/json;charset=UTF-8
+
+              {
+                 "username": "user3",
+                 "email": "user3@example.com",
+                 "active": true,
+                 "roles": [
+                    {"name": "myRole"}
                  ]
               }
 
@@ -130,7 +148,7 @@ class UsersList(AuthenticatedResource):
               {
                   "id": 3,
                   "active": True,
-                  "email": "user3@example.com,
+                  "email": "user3@example.com",
                   "username": "user3",
                   "profileImage": null
               }
@@ -202,7 +220,7 @@ class Users(AuthenticatedResource):
 
            Update a user
 
-           **Example request**:
+           **Example request with ID**:
 
            .. sourcecode:: http
 
@@ -216,7 +234,25 @@ class Users(AuthenticatedResource):
                  "email": "user1@example.com",
                  "active": false,
                  "roles": [
-                     {'id': 1} - or - {'name': 'myRole'}
+                     {"id": 1}
+                 ]
+              }
+
+           **Example request with name**:
+
+           .. sourcecode:: http
+
+              PUT /users/1 HTTP/1.1
+              Host: example.com
+              Accept: application/json, text/javascript
+              Content-Type: application/json;charset=UTF-8
+
+              {
+                 "username": "user1",
+                 "email": "user1@example.com",
+                 "active": false,
+                 "roles": [
+                     {"name": "myRole"}
                  ]
               }
 

requirements-docs.in

@@ -7,6 +7,7 @@ acme
 arrow
 boto3
 botocore
+certsrv
 CloudFlare
 cryptography
 dnspython3
@@ -22,19 +23,26 @@ Flask-Script
 Flask-SQLAlchemy
 flask_replicated
 gunicorn
+hvac # required for the vault destination plugin
 inflection
 josepy
 logmatic-python
 marshmallow-sqlalchemy
 marshmallow<2.20.5 #schema duplicate issues https://github.com/marshmallow-code/marshmallow-sqlalchemy/issues/121
+paramiko  # required for the SFTP destination plugin
 pem
+pyjks >= 19 # pyjks < 19 depends on pycryptodome, which conflicts with dyn's usage of pycrypto
 pyjwt
 pyOpenSSL
 raven[flask]
+redis
 retrying
 SQLAlchemy-Utils
 tabulate
+vine
 xmltodict
+# Test requirements are needed to allow test docs to build
+-r requirements-tests.txt
 
 # docs specific
 sphinx

requirements-docs.txt

@@ -18,6 +18,8 @@ botocore==1.20.7
     # manual debug
 certifi==2020.12.5
     # via requests
+certsrv==2.1.1
+    # manual debug
 chardet==3.0.4
     # via requests
 cloudflare==2.8.15
@@ -32,10 +34,10 @@ docutils==0.15.2
     # via sphinx
 dyn==1.8.1
     # manual debug
-idna==2.9
-    # via requests
-imagesize==1.2.0
-    # via sphinx
+factory-boy==3.2.0
+    # manual debug
+fakeredis==1.4.5
+    # manual debug
 flask==1.1.2
     # manual debug
 flask-bcrypt==0.7.1
@@ -56,8 +58,16 @@ flask-script==2.0.6
     # manual debug
 flask-sqlalchemy==2.4.4
     # manual debug
+freezegun==1.1.0
+    # manual debug
 gunicorn==20.0.4
     # manual debug
+hvac==0.10.8
+    # manual debug
+idna==2.9
+    # via requests
+imagesize==1.2.0
+    # via sphinx
 inflection==0.5.1
     # manual debug
 jinja2==2.11.3
@@ -72,32 +82,46 @@ marshmallow-sqlalchemy==0.23.1
     # manual debug
 marshmallow==2.20.4
     # manual debug
+moto==1.3.16
+    # manual debug
 packaging==20.3
     # via sphinx
+paramiko==2.7.2
+    # manual debug
 pem==21.1.0
     # manual debug
 pygments==2.6.1
     # via sphinx
+pyjks==20.0.0
+    # manual debug
 pyjwt==2.0.1
     # manual debug
 pyopenssl==20.0.1
     # manual debug
 pyparsing==2.4.7
     # via packaging
+pytest==6.2.2
+    # manual debug
 pytz==2019.3
     # via babel
 raven[flask]==6.10.0
     # manual debug
+redis==3.5.3
+    # manual debug
 retrying==1.3.3
     # manual debug
 requests==2.25.1
     # via sphinx
+s3transfer==0.3.3
+    # manual debug
 six==1.15.0
     # via
     #   packaging
     #   sphinxcontrib-httpdomain
 snowballstemmer==2.0.0
     # via sphinx
+soupsieve==2.0.1
+    # manual debug
 sphinx-rtd-theme==0.5.1
     # via -r requirements-docs.in
 sphinx==3.5.0
@@ -119,12 +143,16 @@ sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.4
     # via sphinx
+sqlalchemy==1.3.16
+    # manual debug
 sqlalchemy-utils==0.36.8
     # manual debug
 tabulate==0.8.7
     # manual debug
 urllib3==1.25.8
     # via requests
+vine==1.3.0
+    # manual debug
 xmltodict==0.12.0
     # manual debug