Merge pull request #3426 from jtschladen/fix-docs

Enable fail on warning for docs
This commit is contained in:
Jasmine Schladen 2021-02-18 18:08:07 -08:00 committed by GitHub
commit ad5f7aef82
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
38 changed files with 682 additions and 103 deletions

View File

@ -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

View File

@ -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.

View File

@ -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

View File

@ -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
-----------------------

View File

@ -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:

View File

@ -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:

View File

@ -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:

View File

@ -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:

View File

@ -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:

View File

@ -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:

View File

@ -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:

View File

@ -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:

View File

@ -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:

View File

@ -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:

View File

@ -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:

View File

@ -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:

View File

@ -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:

View File

@ -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

View File

@ -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:

View File

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

View File

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

View File

@ -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

View File

@ -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)

View File

@ -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)

View File

@ -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

View File

@ -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)

View File

@ -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

View File

@ -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):

View File

@ -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):

View File

@ -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

View File

@ -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

View File

@ -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"
}

View File

@ -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)

View File

@ -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;
});

View File

@ -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);
});
});
};

View File

@ -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"}
]
}

View File

@ -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

View File

@ -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