Merge pull request #193 from kevgliss/docs

Improving documentation layout

LICENSE

@@ -1,4 +1,3 @@
-
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/

docs/administration.rst

@@ -24,7 +24,6 @@ Basic Configuration
 
         LOG_FILE = "/logs/lemur/lemur-test.log"
 
-
 .. data:: debug
     :noindex:
 
@@ -34,7 +33,6 @@ Basic Configuration
 
         debug = False
 
-
     .. warning::
         This should never be used in a production environment as it exposes Lemur to
         remote code execution through the debug console.
@@ -173,47 +171,123 @@ Lemur supports sending certification expiration notifications through SES and SM
 .. data:: LEMUR_EMAIL_SENDER
     :noindex:
 
-            Specifies which service will be delivering notification emails. Valid values are `SMTP` or `SES`
+    Specifies which service will be delivering notification emails. Valid values are `SMTP` or `SES`
 
-.. note::
+    .. note::
-    If using STMP as your provider you will need to define additional configuration options as specified by Flask-Mail.
+        If using SMP as your provider you will need to define additional configuration options as specified by Flask-Mail.
-    See: `Flask-Mail <https://pythonhosted.org/Flask-Mail>`_
+        See: `Flask-Mail <https://pythonhosted.org/Flask-Mail>`_
+
+        If you are using SES the email specified by the `LEMUR_MAIL` configuration will need to be verified by AWS before
+        you can send any mail. See: `Verifying Email Address in Amazon SES <http://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses.html>`_
 
-    If you are using SES the email specified by the `LEMUR_MAIL` configuration will need to be verified by AWS before
-    you can send any mail. See: `Verifying Email Address in Amazon SES <http://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses.html>`_
 
 .. data:: LEMUR_MAIL
     :noindex:
 
-            Lemur sender's email
+        Lemur sender's email
 
         ::
 
-        LEMUR_MAIL = 'lemur.example.com'
+            LEMUR_MAIL = 'lemur.example.com'
 
 
 .. data:: LEMUR_SECURITY_TEAM_EMAIL
     :noindex:
 
-            This is an email or list of emails that should be notified when a certificate is expiring. It is also the contact email address for any discovered certificate.
+        This is an email or list of emails that should be notified when a certificate is expiring. It is also the contact email address for any discovered certificate.
 
         ::
 
-        LEMUR_SECURITY_TEAM_EMAIL = ['security@example.com']
+            LEMUR_SECURITY_TEAM_EMAIL = ['security@example.com']
 
 
 .. data:: LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS
     :noindex:
 
-            Lemur notification intervals
+        Lemur notification intervals
 
         ::
 
-        LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS = [30, 15, 2]
+            LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS = [30, 15, 2]
 
 
-Authority Options
+Authentication Options
------------------
+----------------------
+Lemur currently supports Basic Authentication, Ping OAuth2, and Google out of the box. Additional flows can be added relatively easily.
+If you are not using an authentication provider you do not need to configure any of these options.
+
+For more information about how to use social logins, see: `Satellizer <https://github.com/sahat/satellizer>`_
+
+.. data:: ACTIVE_PROVIDERS
+    :noindex:
+
+        ::
+
+            ACTIVE_PROVIDERS = ["ping", "google"]
+
+.. data:: PING_SECRET
+    :noindex:
+
+        ::
+
+            PING_SECRET = 'somethingsecret'
+
+.. data:: PING_ACCESS_TOKEN_URL
+    :noindex:
+
+        ::
+
+            PING_ACCESS_TOKEN_URL = "https://<yourpingserver>/as/token.oauth2"
+
+
+.. data:: PING_USER_API_URL
+    :noindex:
+
+        ::
+
+            PING_USER_API_URL = "https://<yourpingserver>/idp/userinfo.openid"
+
+.. data:: PING_JWKS_URL
+    :noindex:
+
+        ::
+
+            PING_JWKS_URL = "https://<yourpingserver>/pf/JWKS"
+
+.. data:: PING_NAME
+    :noindex:
+
+        ::
+
+            PING_NAME = "Example Oauth2 Provider"
+
+.. data:: PING_CLIENT_ID
+    :noindex:
+
+        ::
+
+            PING_CLIENT_ID = "client-id"
+
+.. data:: GOOGLE_CLIENT_ID
+    :noindex:
+
+        ::
+
+        GOOGLE_CLIENT_ID = "client-id"
+
+.. data:: GOOGLE_SECRET
+    :noindex:
+
+        ::
+
+            GOOGLE_SECRET = "somethingsecret"
+
+
+Plugin Specific Options
+-----------------------
+
+Verisign Issuer Plugin
+^^^^^^^^^^^^^^^^^^^^^^
 
 Authorities will each have their own configuration options. There is currently just one plugin bundled with Lemur,
 Verisign/Symantec. Additional plugins may define additional options. Refer to the plugin's own documentation
@@ -260,87 +334,16 @@ for those plugins.
         This is the root to be used for your CA chain
 
 
-Authentication
---------------
-Lemur currently supports Basic Authentication, Ping OAuth2, and Google out of the box. Additional flows can be added relatively easily.
-If you are not using an authentication provider you do not need to configure any of these options.
 
-For more information about how to use social logins, see: `Satellizer <https://github.com/sahat/satellizer>`_
+AWS Source/Destination Plugin
-
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. data:: ACTIVE_PROVIDERS
-    :noindex:
-
-    ::
-
-        ACTIVE_PROVIDERS = ["ping", "google"]
-
-.. data:: PING_SECRET
-    :noindex:
-
-    ::
-
-        PING_SECRET = 'somethingsecret'
-
-.. data:: PING_ACCESS_TOKEN_URL
-    :noindex:
-
-    ::
-
-        PING_ACCESS_TOKEN_URL = "https://<yourpingserver>/as/token.oauth2"
-
-
-.. data:: PING_USER_API_URL
-    :noindex:
-
-    ::
-
-        PING_USER_API_URL = "https://<yourpingserver>/idp/userinfo.openid"
-
-.. data:: PING_JWKS_URL
-    :noindex:
-
-    ::
-
-        PING_JWKS_URL = "https://<yourpingserver>/pf/JWKS"
-
-.. data:: PING_NAME
-    :noindex:
-
-    ::
-
-        PING_NAME = "Example Oauth2 Provider"
-
-.. data:: PING_CLIENT_ID
-    :noindex:
-
-    ::
-
-        PING_CLIENT_ID = "client-id"
-
-.. data:: GOOGLE_CLIENT_ID
-    :noindex:
-
-    ::
-
-        GOOGLE_CLIENT_ID = "client-id"
-
-.. data:: GOOGLE_SECRET
-    :noindex:
-
-    ::
-
-        GOOGLE_SECRET = "somethingsecret"
-
-
-AWS Plugin Configuration
-========================
 
 In order for Lemur to manage its own account and other accounts we must ensure it has the correct AWS permissions.
 
 .. note:: AWS usage is completely optional. Lemur can upload, find and manage TLS certificates in AWS. But is not required to do so.
 
 Setting up IAM roles
---------------------
+""""""""""""""""""""
 
 Lemur's AWS plugin uses boto heavily to talk to all the AWS resources it manages. By default it uses the on-instance credentials to make the necessary calls.
 
@@ -445,7 +448,8 @@ IAM-ServerCertificate
 
 
 Setting up STS access
----------------------
+"""""""""""""""""""""
+
 Once we have setup our accounts we need to ensure that we create a trust relationship so that LemurInstanceProfile can assume the Lemur role.
 
 In the AWS console select the Lemur IAM role and select the Trust Relationships tab and click Edit Trust Relationship
@@ -472,7 +476,7 @@ Below is an example policy:
 
 
 Adding N+1 accounts
--------------------
+"""""""""""""""""""
 
 To add another account we go to the new account and create a new Lemur IAM role with the same policy as above.
 
@@ -500,7 +504,7 @@ An example policy:
     }
 
 Setting up SES
---------------
+""""""""""""""
 
 Lemur has built in support for sending it's certificate notifications via Amazon's simple email service (SES). To force
 Lemur to use SES ensure you are the running as the IAM role defined above and that you have followed the steps outlined
@@ -515,23 +519,6 @@ Will be the sender of all notifications, so ensure that it is verified with AWS.
 SES if the default notification gateway and will be used unless SMTP settings are configured in the application configuration
 settings.
 
-Upgrading Lemur
-===============
-
-Lemur provides an easy way to upgrade between versions. Simply download the newest
-version of Lemur from pypi and then apply any schema changes with the following command.
-
-.. code-block:: bash
-
-    $ lemur db upgrade
-
-.. note:: Internally, this uses `Alembic <https://alembic.readthedocs.org/en/latest/>`_ to manage database migrations.
-
-.. note:: By default Alembic looks for the `migrations` folder in the current working directory. 
-The migrations folder is located under `<LEMUR_HOME>/lemur/migrations` if you are running the lemur command from any
-location besides `<LEMUR_HOME>/lemur` you will need to pass the `-d` flag to specify the absolute file path to the 
-`migrations` folder.
-
 .. _CommandLineInterface:
 
 Command Line Interface
@@ -641,32 +628,6 @@ and to get help on sub-commands
         lemur certificates --help
 
 
-Identity and Access Management
-==============================
-
-Lemur uses a Role Based Access Control (RBAC) mechanism to control which users have access to which resources. When a
-user is first created in Lemur they can be assigned one or more roles. These roles are typically dynamically created
-depending on a external identity provider (Google, LDAP, etc.,) or are hardcoded within Lemur and associated with special
-meaning.
-
-Within Lemur there are three main permissions: AdminPermission, CreatorPermission, OwnerPermission. Sub-permissions such
-as ViewPrivateKeyPermission are compositions of these three main Permissions.
-
-Lets take a look at how these permissions are used:
-
-Each `Authority` has a set of roles associated with it. If a user is also associated with the same roles
-that the `Authority` is associated with, Lemur allows that user to user/view/update that `Authority`.
-
-This RBAC is also used when determining which users can access which certificate private key. Lemur's current permission
-structure is setup such that if the user is a `Creator` or `Owner` of a given certificate they are allow to view that
-private key. Owners can also be a role name, such that any user with the same role as owner will be allowed to view the
-private key information.
-
-These permissions are applied to the user upon login and refreshed on every request.
-
-.. seealso::
-    `Flask-Principal <https://pythonhosted.org/Flask-Principal>`_
-
 
 Upgrading Lemur
 ===============
@@ -697,3 +658,61 @@ After you have the latest version of the Lemur code base you must run any needed
 
 
 This will ensure that any needed tables or columns are created or destroyed.
+
+.. note::
+    Internally, this uses `Alembic <https://alembic.readthedocs.org/en/latest/>`_ to manage database migrations.
+
+.. note::
+    By default Alembic looks for the `migrations` folder in the current working directory.The migrations folder is
+    located under `<LEMUR_HOME>/lemur/migrations` if you are running the lemur command from any location besides
+    `<LEMUR_HOME>/lemur` you will need to pass the `-d` flag to specify the absolute file path to the `migrations` folder.
+
+Plugins
+=======
+
+There are several interfaces currently available to extend Lemur. These are a work in
+progress and the API is not frozen.
+
+Bundled Plugins
+---------------
+
+Lemur includes several plugins by default. Including extensive support for AWS, VeriSign/Symantec and CloudCA services.
+
+3rd Party Extensions
+--------------------
+
+The following extensions are available and maintained by members of the Lemur community:
+
+Have an extension that should be listed here? Submit a `pull request <https://github.com/netflix/lemur>`_ and we'll
+get it added.
+
+Want to create your own extension? See :doc:`../developer/plugins/index` to get started.
+
+
+Identity and Access Management
+==============================
+
+Lemur uses a Role Based Access Control (RBAC) mechanism to control which users have access to which resources. When a
+user is first created in Lemur they can be assigned one or more roles. These roles are typically dynamically created
+depending on a external identity provider (Google, LDAP, etc.,) or are hardcoded within Lemur and associated with special
+meaning.
+
+Within Lemur there are three main permissions: AdminPermission, CreatorPermission, OwnerPermission. Sub-permissions such
+as ViewPrivateKeyPermission are compositions of these three main Permissions.
+
+Lets take a look at how these permissions are used:
+
+Each `Authority` has a set of roles associated with it. If a user is also associated with the same roles
+that the `Authority` is associated with, Lemur allows that user to user/view/update that `Authority`.
+
+This RBAC is also used when determining which users can access which certificate private key. Lemur's current permission
+structure is setup such that if the user is a `Creator` or `Owner` of a given certificate they are allow to view that
+private key. Owners can also be a role name, such that any user with the same role as owner will be allowed to view the
+private key information.
+
+These permissions are applied to the user upon login and refreshed on every request.
+
+.. seealso::
+
+    `Flask-Principal <https://pythonhosted.org/Flask-Principal>`_
+

docs/conf.py

@@ -101,9 +101,13 @@ pygments_style = 'sphinx'
 
 # -- Options for HTML output ----------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
-# a list of builtin themes.
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-html_theme = 'default'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/developer/index.rst

@@ -180,19 +180,92 @@ You can see a list of open pull requests (pending changes) by visiting https://g
 
 Pull requests should be against **master** and pass all TravisCI checks
 
-Plugins
+
-=======
+Writing a Plugin
+================
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
 
     plugins/index
 
+
+REST API
+========
+
+Lemur's front end is entirely API driven. Any action that you can accomplish via the UI can also be accomplished by the
+UI. The following is documents and provides examples on how to make requests to the Lemur API.
+
+Authentication
+--------------
+
+.. automodule:: lemur.auth.views
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Destinations
+------------
+
+.. automodule:: lemur.destinations.views
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Notifications
+-------------
+
+.. automodule:: lemur.notifications.views
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Users
+-----
+
+.. automodule:: lemur.users.views
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Roles
+-----
+
+.. automodule:: lemur.roles.views
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Certificates
+------------
+
+.. automodule:: lemur.certificates.views
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Authorities
+-----------
+
+.. automodule:: lemur.authorities.views
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Domains
+-------
+
+.. automodule:: lemur.domains.views
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 Internals
 =========
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
 
     internals/lemur
 

docs/developer/internals/lemur.plugins.rst

@@ -27,6 +27,5 @@ Subpackages
     lemur.plugins.base
     lemur.plugins.bases
     lemur.plugins.lemur_aws
-    lemur.plugins.lemur_cloudca
     lemur.plugins.lemur_email
     lemur.plugins.lemur_verisign

docs/developer/internals/lemur.rst

@@ -96,5 +96,4 @@ Subpackages
     lemur.notifications
     lemur.plugins
     lemur.roles
-    lemur.status
     lemur.users

docs/developer/internals/lemur.status.rst

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

docs/developer/plugins/index.rst

@@ -1,6 +1,3 @@
-Writing a Plugin
-================
-
 Several interfaces exist for extending Lemur:
 
 * Issuer (lemur.plugins.base.issuer)

docs/developer/rest.rst

@@ -1,66 +0,0 @@
-Lemur's front end is entirely API driven. Any action that you can accomplish via the UI can also be accomplished by the
-UI. The following is documents and provides examples on how to make requests to the Lemur API.
-
-Authentication
---------------
-
-.. automodule:: lemur.auth.views
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Destinations
-------------
-
-.. automodule:: lemur.destinations.views
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Notifications
--------------
-
-.. automodule:: lemur.notifications.views
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Users
------
-
-.. automodule:: lemur.users.views
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Roles
------
-
-.. automodule:: lemur.roles.views
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Certificates
-------------
-
-.. automodule:: lemur.certificates.views
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Authorities
------------
-
-.. automodule:: lemur.authorities.views
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Domains
--------
-
-.. automodule:: lemur.domains.views
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/index.rst

@@ -27,8 +27,7 @@ Administration
 .. toctree::
     :maxdepth: 2
 
-    administration/index
+    administration
-    plugins/index
 
 Developers
 ----------
@@ -38,14 +37,21 @@ Developers
 
     developer/index
 
-
+Security
-REST API
 --------
 
 .. toctree::
     :maxdepth: 2
 
-    developer/rest
+    security
+
+Doing a Release
+---------------
+
+.. toctree::
+    :maxdepth: 1
+
+    doing-a-release
 
 FAQ
 ----

docs/plugins/index.rst

@@ -1,20 +0,0 @@
-Plugins
-=======
-
-There are several interfaces currently available to extend Lemur. These are a work in
-progress and the API is not frozen.
-
-Bundled Plugins
----------------
-
-Lemur includes several plugins by default. Including extensive support for AWS, VeriSign/Symantec and CloudCA services.
-
-3rd Party Extensions
---------------------
-
-The following extensions are available and maintained by members of the Lemur community:
-
-Have an extension that should be listed here? Submit a `pull request <https://github.com/netflix/lemur>`_ and we'll
-get it added.
-
-Want to create your own extension? See :doc:`../developer/plugins/index` to get started.

lemur/authorities/service.py

@@ -28,7 +28,6 @@ def update(authority_id, description=None, owner=None, active=None, roles=None):
 
     :param authority_id:
     :param roles: roles that are allowed to use this authority
-    :rtype : Authority
     :return:
     """
     authority = get(authority_id)
@@ -47,7 +46,6 @@ def create(kwargs):
     """
     Create a new authority.
 
-    :rtype : Authority
     :return:
     """
 
@@ -123,7 +121,6 @@ def get(authority_id):
     """
     Retrieves an authority given it's ID
 
-    :rtype : Authority
     :param authority_id:
     :return:
     """
@@ -135,7 +132,6 @@ def get_by_name(authority_name):
     Retrieves an authority given it's name.
 
     :param authority_name:
-    :rtype : Authority
     :return:
     """
     return database.get(Authority, authority_name, field='name')