Adding attributes that were not auto documented

Author: rayluo

docs/conf.py

@@ -62,7 +62,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.
@@ -95,7 +95,7 @@
 # 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']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/index.rst

@@ -7,8 +7,6 @@ MSAL Python Documentation
    :caption: Contents:
    :hidden:
 
-   index
-
 ..
     Comment: Perhaps because of the theme, only the first level sections will show in TOC,
     regardless of maxdepth setting.
@@ -26,7 +24,7 @@ MSAL Python supports some of them.
 **The following diagram serves as a map. Locate your application scenario on the map.**
 **If the corresponding icon is clickable, it will bring you to an MSAL Python sample for that scenario.**
 
-* Most authentication scenarios acquire tokens on behalf of signed-in users.
+* Most authentication scenarios acquire tokens representing the signed-in user.
 
   .. raw:: html
 
@@ -46,7 +44,7 @@ MSAL Python supports some of them.
             alt="Browserless app" title="Browserless app" href="https://github.com/Azure-Samples/ms-identity-python-devicecodeflow">
     </map>
 
-* There are also daemon apps. In these scenarios, applications acquire tokens on behalf of themselves with no user.
+* There are also daemon apps, who acquire tokens representing themselves, not a user.
 
   .. raw:: html
 
@@ -66,26 +64,24 @@ MSAL Python supports some of them.
 
 API Reference
 =============
+.. note::
+
+    Only the contents inside
+    `this source file <https://github.com/AzureAD/microsoft-authentication-library-for-python/blob/dev/msal/__init__.py>`_
+    and their documented methods (unless otherwise marked as deprecated)
+    are MSAL Python public API,
+    which are guaranteed to be backward-compatible until the next major version.
+
+    Everything else, regardless of their naming, are all internal helpers,
+    which could change at anytime in the future, without prior notice.
 
 The following section is the API Reference of MSAL Python.
-The API Reference is like a dictionary. You **read this API section when and only when**:
+The API Reference is like a dictionary, which is useful when:
 
 * You already followed our sample(s) above and have your app up and running,
   but want to know more on how you could tweak the authentication experience
   by using other optional parameters (there are plenty of them!)
-* You read the MSAL Python source code and found a helper function that is useful to you,
-  then you would want to double check whether that helper is documented below.
-  Only documented APIs are considered part of the MSAL Python public API,
-  which are guaranteed to be backward-compatible in MSAL Python 1.x series.
-  Undocumented internal helpers are subject to change anytime, without prior notice.
-
-.. note::
-
-    Only APIs and their parameters documented in this section are part of public API,
-    with guaranteed backward compatibility for the entire 1.x series.
-
-    Other modules in the source code are all considered as internal helpers,
-    which could change at anytime in the future, without prior notice.
+* Some important features have their in-depth documentations in the API Reference.
 
 MSAL proposes a clean separation between
 `public client applications and confidential client applications
@@ -109,6 +105,7 @@ PublicClientApplication
 .. autoclass:: msal.PublicClientApplication
    :members:
 
+   .. autoattribute:: msal.PublicClientApplication.CONSOLE_WINDOW_HANDLE
    .. automethod:: __init__
 
 ConfidentialClientApplication
@@ -134,6 +131,15 @@ See `SerializableTokenCache` for example.
 .. autoclass:: msal.SerializableTokenCache
    :members:
 
+Prompt
+------
+.. autoclass:: msal.Prompt
+   :members:
+
+   .. autoattribute:: msal.Prompt.SELECT_ACCOUNT
+   .. autoattribute:: msal.Prompt.NONE
+   .. autoattribute:: msal.Prompt.CONSENT
+   .. autoattribute:: msal.Prompt.LOGIN
 
 PopAuthScheme
 -------------
@@ -146,6 +152,11 @@ New in MSAL Python 1.26
 .. autoclass:: msal.PopAuthScheme
    :members:
 
+   .. autoattribute:: msal.PopAuthScheme.HTTP_GET
+   .. autoattribute:: msal.PopAuthScheme.HTTP_POST
+   .. autoattribute:: msal.PopAuthScheme.HTTP_PUT
+   .. autoattribute:: msal.PopAuthScheme.HTTP_DELETE
+   .. autoattribute:: msal.PopAuthScheme.HTTP_PATCH
    .. automethod:: __init__
 
 

msal/application.py

@@ -737,10 +737,11 @@ def initiate_auth_code_flow(
             maintain state between the request and callback.
             If absent, this library will automatically generate one internally.
         :param str prompt:
-            By default, no prompt value will be sent, not even "none".
+            By default, no prompt value will be sent, not even string ``"none"``.
             You will have to specify a value explicitly.
-            Its valid values are defined in Open ID Connect specs
-            https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
+            Its valid values are the constants defined in
+            :class:`Prompt <msal.Prompt>`.
+
         :param str login_hint:
             Optional. Identifier of the user. Generally a User Principal Name (UPN).
         :param domain_hint:
@@ -840,10 +841,10 @@ def get_authorization_request_url(
             `not recommended <https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-implicit-grant-flow#is-the-implicit-grant-suitable-for-my-app>`_.
 
         :param str prompt:
-            By default, no prompt value will be sent, not even "none".
+            By default, no prompt value will be sent, not even string ``"none"``.
             You will have to specify a value explicitly.
-            Its valid values are defined in Open ID Connect specs
-            https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
+            Its valid values are the constants defined in
+            :class:`Prompt <msal.Prompt>`.
         :param nonce:
             A cryptographically random value used to mitigate replay attacks. See also
             `OIDC specs <https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest>`_.
@@ -1819,10 +1820,10 @@ def acquire_token_interactive(
         :param list scopes:
             It is a list of case-sensitive strings.
         :param str prompt:
-            By default, no prompt value will be sent, not even "none".
+            By default, no prompt value will be sent, not even string ``"none"``.
             You will have to specify a value explicitly.
-            Its valid values are defined in Open ID Connect specs
-            https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
+            Its valid values are the constants defined in
+            :class:`Prompt <msal.Prompt>`.
         :param str login_hint:
             Optional. Identifier of the user. Generally a User Principal Name (UPN).
         :param domain_hint:
@@ -1867,11 +1868,15 @@ def acquire_token_interactive(
             New in version 1.15.
 
         :param int parent_window_handle:
-            OPTIONAL. If your app is a GUI app running on modern Windows system,
-            and your app opts in to use broker,
+            Required if your app is running on Windows and opted in to use broker.
+
+            If your app is a GUI app,
             you are recommended to also provide its window handle,
             so that the sign in UI window will properly pop up on top of your window.
 
+            If your app is a console app (most Python scripts are console apps),
+            you can use a placeholder value ``msal.PublicClientApplication.CONSOLE_WINDOW_HANDLE``.
+
             New in version 1.20.0.
 
         :param function on_before_launching_ui: